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

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

[Michael Lohmann]

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(-)

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)

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

[René Scharfe]

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.

> 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`.

> +
> +'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

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

[Elijah Newren]

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:
>
> 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.

> > 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.

>  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.

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

[Junio C Hamano]

René Scharfe <l.s.r@web.de> writes:

>> +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.

> 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.

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

[René Scharfe]

Am 20.12.23 um 17:29 schrieb Elijah Newren:
>
> 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é

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

[Michael Lohmann]

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...

> 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.

> > 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.

> > 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)

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

[Michael Lohmann]

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(-)

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)

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

[Michael Lohmann]

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(-)

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)

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

[Elijah Newren]

Hi,

On Wed, Dec 20, 2023 at 11:54 AM Michael Lohmann <mial.lohmann@gmail.com> wrote:
>
> 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`.

> 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.

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

[Junio C Hamano]

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.

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

[Michael Lohmann]

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(-)

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)

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

[Junio C Hamano]

Michael Lohmann <mial.lohmann@gmail.com> writes:

> 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.

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

[Michael Lohmann]

> 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...