threads / patch / 60637

patchDocumentation/git-merge.txt: fix reference to synopsys

Subject: [PATCH] Documentation/git-merge.txt: fix reference to synopsys

## tl;dr

13 messages between Dec 20, 2023 and Dec 20, 2023. Diffs are folded; open one to read it.

replies: 12people: 4as markdown or json

Michael Lohmann· Dec 20, 2023, 07:05 UTC · lore

437591a9d738 changed the synopsys from two separate lines for `--abort` and `--continue` to a single line (and it also simultaneously added `--quit`). That way the "enumeration" of the syntax for `--continue` is no longer valid. Since `--quit` is now also part of the same syntax line, a general statement cannot be made any more. Instead of trying to enumerate the synopsys, be explicit in the limitations of when respective actions are valid.

This change also groups `--abort` and `--continue` together when explaining the circumstances under which they can be run in order to avoid duplication.

Signed-off-by: Michael Lohmann <mi.al.lohmann@gmail.com>
---
 Documentation/git-merge.txt | 19 +++++++++----------
 1 file changed, 9 insertions(+), 10 deletions(-)
Show changes to Documentation/git-merge.txt +9 −10
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e8ab340319..d8863cc943 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -46,21 +46,20 @@ a log message from the user describing the changes. Before the operation,
     D---E---F---G---H master
 ------------
 
-The second syntax ("`git merge --abort`") can only be run after the
-merge has resulted in conflicts. 'git merge --abort' will abort the
-merge process and try to reconstruct the pre-merge state. However,
-if there were uncommitted changes when the merge started (and
-especially if those changes were further modified after the merge
-was started), 'git merge --abort' will in some cases be unable to
-reconstruct the original (pre-merge) changes. Therefore:
+It is possible that a merge failure will prevent this process from being
+completely automatic. "`git merge --continue`" and "`git merge --abort`"
+can only be run after the merge has resulted in conflicts.
+
+'git merge --abort' will abort the merge process and try to reconstruct
+the pre-merge state. However, if there were uncommitted changes when the
+merge started (and especially if those changes were further modified
+after the merge was started), 'git merge --abort' will in some cases be
+unable to reconstruct the original (pre-merge) changes. Therefore:
 
 *Warning*: Running 'git merge' with non-trivial uncommitted changes is
 discouraged: while possible, it may leave you in a state that is hard to
 back out of in the case of a conflict.
 
-The third syntax ("`git merge --continue`") can only be run after the
-merge has resulted in conflicts.
-
 OPTIONS
 -------
 :git-merge: 1

-- 
2.39.3 (Apple Git-145)
René Scharfe· Dec 20, 2023, 15:43 UTC · re: Michael Lohmann · lore

Re: [PATCH] Documentation/git-merge.txt: fix reference to synopsys

Am 20.12.23 um 08:05 schrieb Michael Lohmann:
Thank you for this patch and sorry for the nitpicking below!
> 437591a9d738 changed the synopsys from two separate lines for `--abort`
"Synopsys" is a software company.  A "synopsis" is a brief outline.
Show 6 quoted lines
> and `--continue` to a single line (and it also simultaneously added
> `--quit`). That way the "enumeration" of the syntax for `--continue` is
> no longer valid. Since `--quit` is now also part of the same syntax
> line, a general statement cannot be made any more. Instead of trying to
> enumerate the synopsys, be explicit in the limitations of when
> respective actions are valid.

Had to think a moment before I understood that "enumeration" refers to "The second syntax" and "The third syntax", which have been combined into this line:

       git merge (--continue | --abort | --quit)

And it does make sense that we can no longer say "second syntax" and only refer to "git merge --abort", or "third syntax" and mean "git merge --continue". In other words: References by number are no longer valid after a merge of some of the synopses.

Show 26 quoted lines
> This change also groups `--abort` and `--continue` together when
> explaining the circumstances under which they can be run in order to
> avoid duplication.
>
> Signed-off-by: Michael Lohmann <mi.al.lohmann@gmail.com>
> ---
>  Documentation/git-merge.txt | 19 +++++++++----------
>  1 file changed, 9 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index e8ab340319..d8863cc943 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -46,21 +46,20 @@ a log message from the user describing the changes. Before the operation,
>      D---E---F---G---H master
>  ------------
>
> -The second syntax ("`git merge --abort`") can only be run after the
> -merge has resulted in conflicts. 'git merge --abort' will abort the
> -merge process and try to reconstruct the pre-merge state. However,
> -if there were uncommitted changes when the merge started (and
> -especially if those changes were further modified after the merge
> -was started), 'git merge --abort' will in some cases be unable to
> -reconstruct the original (pre-merge) changes. Therefore:
> +It is possible that a merge failure will prevent this process from being
> +completely automatic. "`git merge --continue`" and "`git merge --abort`"
              ^^^^^^^^^
              automatically
> +can only be run after the merge has resulted in conflicts.

The connection between these two sentences feels weak to me. Are "merge failure" and "conflicts" the same? Perhaps something like this:

   A merge stops if there's a conflict that cannot be resolved
   automatically.  At that point you can run `git merge --abort` or
   `git merge --continue`.
Show 13 quoted lines
> +
> +'git merge --abort' will abort the merge process and try to reconstruct
> +the pre-merge state. However, if there were uncommitted changes when the
> +merge started (and especially if those changes were further modified
> +after the merge was started), 'git merge --abort' will in some cases be
> +unable to reconstruct the original (pre-merge) changes. Therefore:
>
>  *Warning*: Running 'git merge' with non-trivial uncommitted changes is
>  discouraged: while possible, it may leave you in a state that is hard to
>  back out of in the case of a conflict.
>
> -The third syntax ("`git merge --continue`") can only be run after the
> -merge has resulted in conflicts.

What's with the quoting? It was inconsistent before, but I wonder what would be correct here. Switching between straight single quotes ('') and curved double quotes ("``") seems a bit arbitrary.

And I'm not even sure if these quotes really are what I think they are based on https://docs.asciidoctor.org/asciidoc/latest/subs/quotes/. On https://git-scm.com/docs/git-merge single quotes get rendered as <em>, backticks as <code> (which makes sense) and curved double quotes as <code> surrounded by straight double quotes (which looks weird).

The only guidance I found is this paragraph from CodingGuidelines:
   Literal examples (e.g. use of command-line options, command names,
   branch names, URLs, pathnames (files and directories), configuration and
   environment variables) must be typeset in monospace (i.e. wrapped with
   backticks)

So shouldn't we wrap all commands in backticks and nothing more? Probably worth a separate patch.

> -
>  OPTIONS
>  -------
>  :git-merge: 1
Elijah Newren· Dec 20, 2023, 16:29 UTC · re: René Scharfe · lore

Re: [PATCH] Documentation/git-merge.txt: fix reference to synopsys

Hi,
I'm getting in on the fun by adding a little nit-picking of my own.  :-)
On Wed, Dec 20, 2023 at 7:46 AM René Scharfe <l.s.r@web.de> wrote:
Show 26 quoted lines
>
> Am 20.12.23 um 08:05 schrieb Michael Lohmann:
>
> Thank you for this patch and sorry for the nitpicking below!
>
> > 437591a9d738 changed the synopsys from two separate lines for `--abort`
>
> "Synopsys" is a software company.  A "synopsis" is a brief outline.
>
> > and `--continue` to a single line (and it also simultaneously added
> > `--quit`). That way the "enumeration" of the syntax for `--continue` is
> > no longer valid. Since `--quit` is now also part of the same syntax
> > line, a general statement cannot be made any more. Instead of trying to
> > enumerate the synopsys, be explicit in the limitations of when
> > respective actions are valid.
>
> Had to think a moment before I understood that "enumeration" refers to
> "The second syntax" and "The third syntax", which have been combined
> into this line:
>
>        git merge (--continue | --abort | --quit)
>
> And it does make sense that we can no longer say "second syntax" and
> only refer to "git merge --abort", or "third syntax" and mean "git
> merge --continue".  In other words: References by number are no longer
> valid after a merge of some of the synopses.

Thanks for explaining; I also missed that in reading over the original patch. It'd be great if Michael could update the commit message to make this a bit more clear.

Show 28 quoted lines
> > This change also groups `--abort` and `--continue` together when
> > explaining the circumstances under which they can be run in order to
> > avoid duplication.
> >
> > Signed-off-by: Michael Lohmann <mi.al.lohmann@gmail.com>
> > ---
> >  Documentation/git-merge.txt | 19 +++++++++----------
> >  1 file changed, 9 insertions(+), 10 deletions(-)
> >
> > diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> > index e8ab340319..d8863cc943 100644
> > --- a/Documentation/git-merge.txt
> > +++ b/Documentation/git-merge.txt
> > @@ -46,21 +46,20 @@ a log message from the user describing the changes. Before the operation,
> >      D---E---F---G---H master
> >  ------------
> >
> > -The second syntax ("`git merge --abort`") can only be run after the
> > -merge has resulted in conflicts. 'git merge --abort' will abort the
> > -merge process and try to reconstruct the pre-merge state. However,
> > -if there were uncommitted changes when the merge started (and
> > -especially if those changes were further modified after the merge
> > -was started), 'git merge --abort' will in some cases be unable to
> > -reconstruct the original (pre-merge) changes. Therefore:
> > +It is possible that a merge failure will prevent this process from being
> > +completely automatic. "`git merge --continue`" and "`git merge --abort`"
>               ^^^^^^^^^
>               automatically

Do you perhaps mean "completed automatically" (i.e. change both of the last two words in that sentence, and not just the last one)? That would make sense to me, and I like that wording a little better. But I think either you need to change both of the last two words of that sentence (my preference), or neither of them.

> > +can only be run after the merge has resulted in conflicts.
>
> The connection between these two sentences feels weak to me.

This sentence is a bit more problematic than that: Even when there are no conflicts, "git merge --no-commit" will also stop a merge, and one can then use either --abort or --continue. So the assertion made by this sentence that you're reviewing is not accurate.

Show 5 quoted lines
>  Perhaps something like this:
>
>    A merge stops if there's a conflict that cannot be resolved
>    automatically.  At that point you can run `git merge --abort` or
>    `git merge --continue`.

I like this alternative wording; it avoids the incorrect assertion and uses something equivalent to the "completed automatically" suggested above.

René Scharfe· Dec 20, 2023, 17:18 UTC · re: Elijah Newren · lore

Re: [PATCH] Documentation/git-merge.txt: fix reference to synopsys

Am 20.12.23 um 17:29 schrieb Elijah Newren:
Show 12 quoted lines
>
> On Wed, Dec 20, 2023 at 7:46 AM René Scharfe <l.s.r@web.de> wrote:
>>
>> Am 20.12.23 um 08:05 schrieb Michael Lohmann:
>>
>>> +It is possible that a merge failure will prevent this process from being
>>> +completely automatic. "`git merge --continue`" and "`git merge --abort`"
>>               ^^^^^^^^^
>>               automatically
>
> Do you perhaps mean "completed automatically" (i.e. change both of the
> last two words in that sentence, and not just the last one)?

Possibly. This looks like a case of me making a mistake while criticizing someone else's grammar, though. Which happens almost every time. o_O

René
Junio C Hamano· Dec 20, 2023, 16:51 UTC · re: René Scharfe · lore

Re: [PATCH] Documentation/git-merge.txt: fix reference to synopsys

René Scharfe <l.s.r@web.de> writes:
Show 13 quoted lines
>> +It is possible that a merge failure will prevent this process from being
>> +completely automatic. "`git merge --continue`" and "`git merge --abort`"
>               ^^^^^^^^^
>               automatically
>
>> +can only be run after the merge has resulted in conflicts.
>
> The connection between these two sentences feels weak to me.  Are "merge
> failure" and "conflicts" the same?  Perhaps something like this:
>
>    A merge stops if there's a conflict that cannot be resolved
>    automatically.  At that point you can run `git merge --abort` or
>    `git merge --continue`.

Just being nitpicky and curious, but does the abort/continue also apply when you run "git merge --no-commit"?

I do not do documentation all that much these days, but when I was involved heavily in discussions on documentation patches, I often said "'git merge' gives back control to the user" to refer to both cases, either because it couldn't complete the work it was asked to do, or because it was asked to stop before completing the work.

Show 9 quoted lines
> The only guidance I found is this paragraph from CodingGuidelines:
>
>    Literal examples (e.g. use of command-line options, command names,
>    branch names, URLs, pathnames (files and directories), configuration and
>    environment variables) must be typeset in monospace (i.e. wrapped with
>    backticks)
>
> So shouldn't we wrap all commands in backticks and nothing more?
> Probably worth a separate patch.
Thanks for a good review.
Michael Lohmann· Dec 20, 2023, 19:53 UTC · re: René Scharfe · lore

[PATCH 0/2] Documentation/git-merge.txt: fix reference to synopsis

Hey!
Thank you all for your great reviews!
> Thank you for this patch and sorry for the nitpicking below!

No need to be sorry - this is what I am here for since it is the only way to learn ;-) (also I am not a native speaker, so I know I am constantly making mistakes)

> "Synopsys" is a software company.  A "synopsis" is a brief outline.

Oh yeah... Now I need a face-palm emoji :D This is what you get from trusting the spell check for words you just tried to copy far too early in the morning... And another thing to learn for me: don't submit patches while you are not yet fully awake... Sorry for everyone who had to read the first draft! That was indeed not very professional from me...

Show 10 quoted lines
> Had to think a moment before I understood that "enumeration" refers to
> "The second syntax" and "The third syntax", which have been combined
> into this line:
>
>        git merge (--continue | --abort | --quit)
>
> And it does make sense that we can no longer say "second syntax" and
> only refer to "git merge --abort", or "third syntax" and mean "git
> merge --continue".  In other words: References by number are no longer
> valid after a merge of some of the synopses.

That sums it up a lot better. I wasn't happy with my first draft, but couldn't come up with something better - now I used your explanation with a slight variation.

Show 6 quoted lines
> > The connection between these two sentences feels weak to me.
>
> This sentence is a bit more problematic than that: Even when there are
> no conflicts, "git merge --no-commit" will also stop a merge, and one
> can then use either --abort or --continue.  So the assertion made by
> this sentence that you're reviewing is not accurate.
Oh! Another thing I learned today! Thanks a lot for pointing that out!

I have to confess: I copied that sentence 1:1 from git-rebase - that is also why it did not fit in with the next sentence... But Renés suggestion just avoids this (and the "--continue") problem altogether, so I went with a slight variation of it instead.

> I like this alternative wording
Same! I fumbled around with it just a bit to include your hint
> Possibly.  This looks like a case of me making a mistake while
> criticizing someone else's grammar, though.  Which happens almost
> every time. o_O

We all make mistakes (and my own grammar is horrific...), but the more I appreciate it when people suggest/ask things because that always gives me the opportunity to learn as well. And you are totally right in that this sentence does not "feel quite right" anyways, so I understand your unease with it and why you wanted to discuss it ;-)

> Just being nitpicky and curious, but does the abort/continue also
> apply when you run "git merge --no-commit"?

Yes, indeed that seems to be the case (also pointed out simultaneously by Elijah Newren). I extended Renés suggestion to mention it as well.

Show 11 quoted lines
> > The only guidance I found is this paragraph from CodingGuidelines:
> >
> >    Literal examples (e.g. use of command-line options, command names,
> >    branch names, URLs, pathnames (files and directories), configuration and
> >    environment variables) must be typeset in monospace (i.e. wrapped with
> >    backticks)
> >
> > So shouldn't we wrap all commands in backticks and nothing more?
> > Probably worth a separate patch.
>
> Thanks for a good review.
Indeed! That was very nice!

And I also added the suggested changes as a second patch. It applies just fine to master without the first one, though that obviously would leave the changed paragraphs from the first commit with the mixed syntax, but that would just be a minor inconsistency until the first patch (or a future version of it) is applied.

Cheers Michael

Michael Lohmann (2):
  Documentation/git-merge.txt: fix reference to synopsis
  Documentation/git-merge.txt: use backticks for command wrapping
 Documentation/git-merge.txt | 70 ++++++++++++++++++-------------------
 1 file changed, 35 insertions(+), 35 deletions(-)
-- 
2.39.3 (Apple Git-145)
Michael Lohmann· Dec 20, 2023, 19:53 UTC · re: René Scharfe · lore

[PATCH 1/2] Documentation/git-merge.txt: fix reference to synopsis

437591a9d738 combined the synopsis of "The second syntax" (meaning `git merge --abort`) and "The third syntax" (for `git merge --continue`) into this single line:

       git merge (--continue | --abort | --quit)

but it was still referred to when describing the preconditions that have to be fulfilled to run the respective actions. In other words: References by number are no longer valid after a merge of some of the synopses.

Also the previous version did not acknowledge that `--no-merge` would result in the precondition being fulfilled (thanks to Elijah Newren and Junio C Hamano for pointing that out).

This change also groups `--abort` and `--continue` together when explaining the prerequisites in order to avoid duplication.

Helped-by: René Scharfe <l.s.r@web.de>
Signed-off-by: Michael Lohmann <mi.al.lohmann@gmail.com>
---
 Documentation/git-merge.txt | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)
Show changes to Documentation/git-merge.txt +10 −10
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e8ab340319..33ec5c6b19 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -46,21 +46,21 @@ a log message from the user describing the changes. Before the operation,
     D---E---F---G---H master
 ------------
 
-The second syntax ("`git merge --abort`") can only be run after the
-merge has resulted in conflicts. 'git merge --abort' will abort the
-merge process and try to reconstruct the pre-merge state. However,
-if there were uncommitted changes when the merge started (and
-especially if those changes were further modified after the merge
-was started), 'git merge --abort' will in some cases be unable to
-reconstruct the original (pre-merge) changes. Therefore:
+A merge stops if there's a conflict that cannot be resolved
+automatically or if `--no-commit` was provided when initiating the
+merge. At that point you can run `git merge --abort` or `git merge
+--continue`.
+
+`git merge --abort` will abort the merge process and try to reconstruct
+the pre-merge state. However, if there were uncommitted changes when the
+merge started (and especially if those changes were further modified
+after the merge was started), `git merge --abort` will in some cases be
+unable to reconstruct the original (pre-merge) changes. Therefore:
 
 *Warning*: Running 'git merge' with non-trivial uncommitted changes is
 discouraged: while possible, it may leave you in a state that is hard to
 back out of in the case of a conflict.
 
-The third syntax ("`git merge --continue`") can only be run after the
-merge has resulted in conflicts.
-
 OPTIONS
 -------
 :git-merge: 1

-- 
2.39.3 (Apple Git-145)
Elijah Newren· Dec 20, 2023, 20:45 UTC · re: Michael Lohmann · lore

Re: [PATCH 1/2] Documentation/git-merge.txt: fix reference to synopsis

Hi,
On Wed, Dec 20, 2023 at 11:54 AM Michael Lohmann <mial.lohmann@gmail.com> wrote:
Show 13 quoted lines
>
> 437591a9d738 combined the synopsis of "The second syntax" (meaning `git
> merge --abort`) and "The third syntax" (for `git merge --continue`) into
> this single line:
>
>        git merge (--continue | --abort | --quit)
>
> but it was still referred to when describing the preconditions that have
> to be fulfilled to run the respective actions. In other words:
> References by number are no longer valid after a merge of some of the
> synopses.
>
> Also the previous version did not acknowledge that `--no-merge` would
`--no-commit` rather than `--no-merge`.
Show 50 quoted lines
> result in the precondition being fulfilled (thanks to Elijah Newren and
> Junio C Hamano for pointing that out).
>
> This change also groups `--abort` and `--continue` together when
> explaining the prerequisites in order to avoid duplication.
>
> Helped-by: René Scharfe <l.s.r@web.de>
> Signed-off-by: Michael Lohmann <mi.al.lohmann@gmail.com>
> ---
>  Documentation/git-merge.txt | 20 ++++++++++----------
>  1 file changed, 10 insertions(+), 10 deletions(-)
>
> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index e8ab340319..33ec5c6b19 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -46,21 +46,21 @@ a log message from the user describing the changes. Before the operation,
>      D---E---F---G---H master
>  ------------
>
> -The second syntax ("`git merge --abort`") can only be run after the
> -merge has resulted in conflicts. 'git merge --abort' will abort the
> -merge process and try to reconstruct the pre-merge state. However,
> -if there were uncommitted changes when the merge started (and
> -especially if those changes were further modified after the merge
> -was started), 'git merge --abort' will in some cases be unable to
> -reconstruct the original (pre-merge) changes. Therefore:
> +A merge stops if there's a conflict that cannot be resolved
> +automatically or if `--no-commit` was provided when initiating the
> +merge. At that point you can run `git merge --abort` or `git merge
> +--continue`.
> +
> +`git merge --abort` will abort the merge process and try to reconstruct
> +the pre-merge state. However, if there were uncommitted changes when the
> +merge started (and especially if those changes were further modified
> +after the merge was started), `git merge --abort` will in some cases be
> +unable to reconstruct the original (pre-merge) changes. Therefore:
>
>  *Warning*: Running 'git merge' with non-trivial uncommitted changes is
>  discouraged: while possible, it may leave you in a state that is hard to
>  back out of in the case of a conflict.
>
> -The third syntax ("`git merge --continue`") can only be run after the
> -merge has resulted in conflicts.
> -
>  OPTIONS
>  -------
>  :git-merge: 1
> --
> 2.39.3 (Apple Git-145)
Otherwise, looks good.
Junio C Hamano· Dec 20, 2023, 20:56 UTC · re: Michael Lohmann · lore

Re: [PATCH 1/2] Documentation/git-merge.txt: fix reference to synopsis

Michael Lohmann <mial.lohmann@gmail.com> writes:
> Also the previous version did not acknowledge that `--no-merge` would
> result in the precondition being fulfilled (thanks to Elijah Newren and
> Junio C Hamano for pointing that out).

This does not belong to the log message. Please write for those who only read "git log" output after the work is merged and nothing else. To them, errors in the previous attempt that was pointed out by reviewers and corrected in this version do not exist.

It is perfectly fine to write something like the above after the three-dash line. That is the place to clue reviewers about the context of this round, reminding what happend in the previous iteration and what the differences this round has, etc.

Thanks.
Michael Lohmann· Dec 20, 2023, 21:35 UTC · re: Junio C Hamano · lore

[PATCH v3 1/2] Documentation/git-merge.txt: fix reference to synopsis

437591a9d738 combined the synopsis of "The second syntax" (meaning `git merge --abort`) and "The third syntax" (for `git merge --continue`) into this single line:

       git merge (--continue | --abort | --quit)

but it was still referred to when describing the preconditions that have to be fulfilled to run the respective actions. In other words: References by number are no longer valid after a merge of some of the synopses.

Also the previous version of the documentation did not acknowledge that `--no-commit` would result in the precondition being fulfilled (thanks to Elijah Newren and Junio C Hamano for pointing that out).

This change also groups `--abort` and `--continue` together when explaining the prerequisites in order to avoid duplication.

Helped-by: René Scharfe <l.s.r@web.de>
Signed-off-by: Michael Lohmann <mi.al.lohmann@gmail.com>
---

@Junio My sentence was ambiguous. I wanted to refer to the upstream version of the docs, since that also has the faulty prerequisites, so I changed it to "the previous version of the documentation" for clarification. If you think that this paragraph is not needed nevertheless I am perfectly happy to remove it.

@Elijah Thanks!
 Documentation/git-merge.txt | 20 ++++++++++----------
 1 file changed, 10 insertions(+), 10 deletions(-)
Show changes to Documentation/git-merge.txt +10 −10
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index e8ab340319..33ec5c6b19 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -46,21 +46,21 @@ a log message from the user describing the changes. Before the operation,
     D---E---F---G---H master
 ------------
 
-The second syntax ("`git merge --abort`") can only be run after the
-merge has resulted in conflicts. 'git merge --abort' will abort the
-merge process and try to reconstruct the pre-merge state. However,
-if there were uncommitted changes when the merge started (and
-especially if those changes were further modified after the merge
-was started), 'git merge --abort' will in some cases be unable to
-reconstruct the original (pre-merge) changes. Therefore:
+A merge stops if there's a conflict that cannot be resolved
+automatically or if `--no-commit` was provided when initiating the
+merge. At that point you can run `git merge --abort` or `git merge
+--continue`.
+
+`git merge --abort` will abort the merge process and try to reconstruct
+the pre-merge state. However, if there were uncommitted changes when the
+merge started (and especially if those changes were further modified
+after the merge was started), `git merge --abort` will in some cases be
+unable to reconstruct the original (pre-merge) changes. Therefore:
 
 *Warning*: Running 'git merge' with non-trivial uncommitted changes is
 discouraged: while possible, it may leave you in a state that is hard to
 back out of in the case of a conflict.
 
-The third syntax ("`git merge --continue`") can only be run after the
-merge has resulted in conflicts.
-
 OPTIONS
 -------
 :git-merge: 1

-- 
2.39.3 (Apple Git-145)
Junio C Hamano· Dec 20, 2023, 21:39 UTC · re: Michael Lohmann · lore

Re: [PATCH v3 1/2] Documentation/git-merge.txt: fix reference to synopsis

Michael Lohmann <mial.lohmann@gmail.com> writes:
Show 27 quoted lines
> 437591a9d738 combined the synopsis of "The second syntax" (meaning `git
> merge --abort`) and "The third syntax" (for `git merge --continue`) into
> this single line:
>
>        git merge (--continue | --abort | --quit)
>
> but it was still referred to when describing the preconditions that have
> to be fulfilled to run the respective actions. In other words:
> References by number are no longer valid after a merge of some of the
> synopses.
>
> Also the previous version of the documentation did not acknowledge that
> `--no-commit` would result in the precondition being fulfilled (thanks
> to Elijah Newren and Junio C Hamano for pointing that out).
>
> This change also groups `--abort` and `--continue` together when
> explaining the prerequisites in order to avoid duplication.
>
> Helped-by: René Scharfe <l.s.r@web.de>
> Signed-off-by: Michael Lohmann <mi.al.lohmann@gmail.com>
> ---
>
> @Junio My sentence was ambiguous. I wanted to refer to the upstream
> version of the docs, since that also has the faulty prerequisites, so I
> changed it to "the previous version of the documentation" for
> clarification. If you think that this paragraph is not needed
> nevertheless I am perfectly happy to remove it.
Ah, sorry about the misunderstanding.  Will apply.  Thanks.
Michael Lohmann· Dec 20, 2023, 22:09 UTC · re: Junio C Hamano · lore

Re: [PATCH v3 1/2] Documentation/git-merge.txt: fix reference to synopsis

> Ah, sorry about the misunderstanding.  Will apply.  Thanks.

No need to be sorry - my wording was ambiguous. Thank you for your patience with me! I hope it will get smoother for all of you the more experience I get...

Michael Lohmann· Dec 20, 2023, 19:53 UTC · re: René Scharfe · lore

[PATCH 2/2] Documentation/git-merge.txt: use backticks for command wrapping

As René found in the guidance from CodingGuidelines:
   Literal examples (e.g. use of command-line options, command names,
   branch names, URLs, pathnames (files and directories), configuration
   and environment variables) must be typeset in monospace (i.e. wrapped
   with backticks)

So all instances of single and double quotes for wraping said examples were replaced with simple backticks.

Suggested-by: René Scharfe <l.s.r@web.de>
Signed-off-by: Michael Lohmann <mi.al.lohmann@gmail.com>
---
 Documentation/git-merge.txt | 50 ++++++++++++++++++-------------------
 1 file changed, 25 insertions(+), 25 deletions(-)
Show changes to Documentation/git-merge.txt +25 −25
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 33ec5c6b19..7332f53f2f 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -20,12 +20,12 @@ DESCRIPTION
 -----------
 Incorporates changes from the named commits (since the time their
 histories diverged from the current branch) into the current
-branch.  This command is used by 'git pull' to incorporate changes
+branch.  This command is used by `git pull` to incorporate changes
 from another repository and can be used by hand to merge changes
 from one branch into another.
 
 Assume the following history exists and the current branch is
-"`master`":
+`master`:
 
 ------------
 	  A---B---C topic
@@ -33,7 +33,7 @@ Assume the following history exists and the current branch is
     D---E---F---G master
 ------------
 
-Then "`git merge topic`" will replay the changes made on the
+Then `git merge topic` will replay the changes made on the
 `topic` branch since it diverged from `master` (i.e., `E`) until
 its current commit (`C`) on top of `master`, and record the result
 in a new commit along with the names of the two parent commits and
@@ -57,7 +57,7 @@ merge started (and especially if those changes were further modified
 after the merge was started), `git merge --abort` will in some cases be
 unable to reconstruct the original (pre-merge) changes. Therefore:
 
-*Warning*: Running 'git merge' with non-trivial uncommitted changes is
+*Warning*: Running `git merge` with non-trivial uncommitted changes is
 discouraged: while possible, it may leave you in a state that is hard to
 back out of in the case of a conflict.
 
@@ -74,8 +74,8 @@ include::merge-options.txt[]
 If `--log` is specified, a shortlog of the commits being merged
 will be appended to the specified message.
 +
-The 'git fmt-merge-msg' command can be
-used to give a good default for automated 'git merge'
+The `git fmt-merge-msg` command can be
+used to give a good default for automated `git merge`
 invocations. The automated message can include the branch description.
 
 --into-name <branch>::
@@ -104,14 +104,14 @@ include::rerere-options.txt[]
 	present, apply it to the worktree.
 +
 If there were uncommitted worktree changes present when the merge
-started, 'git merge --abort' will in some cases be unable to
+started, `git merge --abort` will in some cases be unable to
 reconstruct these changes. It is therefore recommended to always
-commit or stash your changes before running 'git merge'.
+commit or stash your changes before running `git merge`.
 +
-'git merge --abort' is equivalent to 'git reset --merge' when
+`git merge --abort` is equivalent to `git reset --merge` when
 `MERGE_HEAD` is present unless `MERGE_AUTOSTASH` is also present in
-which case 'git merge --abort' applies the stash entry to the worktree
-whereas 'git reset --merge' will save the stashed changes in the stash
+which case `git merge --abort` applies the stash entry to the worktree
+whereas `git reset --merge` will save the stashed changes in the stash
 list.
 
 --quit::
@@ -120,8 +120,8 @@ list.
 	stash entry will be saved to the stash list.
 
 --continue::
-	After a 'git merge' stops due to conflicts you can conclude the
-	merge by running 'git merge --continue' (see "HOW TO RESOLVE
+	After a `git merge` stops due to conflicts you can conclude the
+	merge by running `git merge --continue` (see "HOW TO RESOLVE
 	CONFLICTS" section below).
 
 <commit>...::
@@ -144,25 +144,25 @@ PRE-MERGE CHECKS
 Before applying outside changes, you should get your own work in
 good shape and committed locally, so it will not be clobbered if
 there are conflicts.  See also linkgit:git-stash[1].
-'git pull' and 'git merge' will stop without doing anything when
-local uncommitted changes overlap with files that 'git pull'/'git
-merge' may need to update.
+`git pull` and `git merge` will stop without doing anything when
+local uncommitted changes overlap with files that `git pull`/`git
+merge` may need to update.
 
 To avoid recording unrelated changes in the merge commit,
-'git pull' and 'git merge' will also abort if there are any changes
+`git pull` and `git merge` will also abort if there are any changes
 registered in the index relative to the `HEAD` commit.  (Special
 narrow exceptions to this rule may exist depending on which merge
 strategy is in use, but generally, the index must match HEAD.)
 
-If all named commits are already ancestors of `HEAD`, 'git merge'
+If all named commits are already ancestors of `HEAD`, `git merge`
 will exit early with the message "Already up to date."
 
 FAST-FORWARD MERGE
 ------------------
 
 Often the current branch head is an ancestor of the named commit.
-This is the most common case especially when invoked from 'git
-pull': you are tracking an upstream repository, you have committed
+This is the most common case especially when invoked from `git
+pull`: you are tracking an upstream repository, you have committed
 no local changes, and now you want to update to a newer upstream
 revision.  In this case, a new commit is not needed to store the
 combined history; instead, the `HEAD` (along with the index) is
@@ -269,7 +269,7 @@ Barbie's remark on your side.  The only thing you can tell is that your
 side wants to say it is hard and you'd prefer to go shopping, while the
 other side wants to claim it is easy.
 
-An alternative style can be used by setting the "merge.conflictStyle"
+An alternative style can be used by setting the `merge.conflictStyle`
 configuration variable to either "diff3" or "zdiff3".  In "diff3"
 style, the above conflict may look like this:
 
@@ -328,10 +328,10 @@ After seeing a conflict, you can do two things:
 
  * Resolve the conflicts.  Git will mark the conflicts in
    the working tree.  Edit the files into shape and
-   'git add' them to the index.  Use 'git commit' or
-   'git merge --continue' to seal the deal. The latter command
+   `git add` them to the index.  Use `git commit` or
+   `git merge --continue` to seal the deal. The latter command
    checks whether there is a (interrupted) merge in progress
-   before calling 'git commit'.
+   before calling `git commit`.
 
 You can work through the conflict with a number of tools:
 
@@ -392,7 +392,7 @@ CONFIGURATION
 
 branch.<name>.mergeOptions::
 	Sets default options for merging into branch <name>. The syntax and
-	supported options are the same as those of 'git merge', but option
+	supported options are the same as those of `git merge`, but option
 	values containing whitespace characters are currently not supported.
 
 include::includes/cmd-config-section-rest.txt[]

-- 
2.39.3 (Apple Git-145)

← back to recent threads