Re: [PATCH v3 1/6] doc: add new gitmergeconflicts man page

["Julia Evans" <julia@jvns.ca>]

On Mon, Oct 12, 2026, at 2:16 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Julia Evans <julia@jvns.ca>
>>
>> Introduce a new page, `gitmergeconflicts`, that explains the process of
>> handling a merge conflict in a way that addresses the following issues,
>> which came from feedback from Git users on the current explanation of
>> merge conflicts in the `git merge` man page:
>>
>> - The process for resolving a merge conflict is only explained in the
>> ...
>> - It sometimes uses the term "area" and sometimes uses the term "hunk"
>
> It looks a bit annoying that these sentences in the enumeration all
> lack their full stops.

Sure, will fix.

>> Only discuss merge, rebase, cherry-pick, and revert for now even though
>> there are other ways that merge conflicts can happen because it's
>> awkward to talk about `am`, `apply`, and `checkout -m`.
>
> I do not know "because it's awkward" is a good justification,
> though.  "awkward" why?

It's because `apply` and `am` can also apply patches, and that's a whole
separate topic than explaining the 3-way merge. I think explaining the
difference between applying a patch and doing a 3-way merge could
be interesting to do in the future but this is already quite a big patch
series.

> It might be tempting to omit some commands that are less common for
> new users, but we are touching the main part of the technical manual
> that are meant ot be used by everybody, so that is not a good reason
> to choose covering some but not others.
>
> I however agree that it is better to avoid appearing to be complete
> and leaving others (including future ones we add) with "any other
> command that does a merge" as this round of document gives.
>
>> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
>> ...
>> +There are 3 ways to handle a merge conflict:
>> +
>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
>> +  below for details)
>> +* Stop the operation and return your branch to its original state
>> +  with the appropriate `--abort` command, for example `git merge --abort`
>> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
>> +  for how to find the command to run.
>> +* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic
>> +  commit with the appropriate `--skip` command
>
> The third entry is a nice addition.  multi-step anything are the
> same, including revert, right?  I'd recommend updating it to
> something like "if you are in a multi-step operation like `rebase`"
> in the same spirit as the "or any other command" change you made at
> the beginning of this file.

Done.

>> +When there's a merge conflict, Git will update the conflicted file
>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
>> +For example, here's a merge conflict where both sides edited a list of
>> +fruits in different ways -- one side added "cherry" and the other side
>> +added "banana":
>
> You added "-- one side added ..." at the end, which I think sends a
> wrong message.  With rcs-merge style conflict, you cannot simply
> tell, because it is ambiguous.  The original may have had both
> banana and cherry, in which case the sample output shows the result
> of one side removing banana and the other side removing cherry.

Make sense, will replace "added" with "has".

>> +[[diff3]]
>> +DIFF3
>> +-----
>> +
>> +By default, Git doesn't include the original code when formatting
>> +a merge conflict. To include the original code, you can set the
>> +configuration option `merge.conflictstyle` to `diff3`.
>> +This extra context can make it much easier to understand what's
>> +happening in a merge conflict.
>> +
>> +Here's an example of what a merge conflict would look like when using
>> +`diff3`. There's an extra section (between `|||||||` and `=======`)
>> +with the original code.
>> +
>> +With this view, you can see that both sides fixed a spelling
>> +mistake in "mango", and each added one fruit to the list.
>> +
>> +----
>> +FRUITS = [
>> +    "apple",
>> +<<<<<<< HEAD
>> +    "cherry",
>> +    "mango",
>> +||||||| 1c22e48
>> +    "mangoooo",
>> +=======
>> +    "banana",
>> +    "mango",
>> +>>>>>>> add-fruit
>> +    "orange",
>> +]
>> +----
>
> THis is a great example.  
>
> But an even better example would be to give this:
>
>         FRUITS = [
>             "apple",
>         <<<<<<< HEAD
>             "cherry",
>             "mango",
>         ||||||| 1c22e48
>             "banana",
>             "cherry",
>             "mangoooo",
>         =======
>             "banana",
>             "mango",
>         >>>>>>> add-fruit
>             "orange",
>         ]
>
> and tell the readers that that the correct resolution is to have
> "apply, mango, orange", as each of cherry and banana was removed by
> one side while the other side did not touch it.  Having cherry and
> banana in the result is a tempting but not always correct conclusion
> unexperienced people would draw from the rcs-merge style output that
> is ambiguous, and here is a great place to teach it in this flow.

Thanks, this is a much better example, for the reasons you say. Will use it.

I always appreciate thinking carefully about which examples to give,
it's so important.

> Especially because it would make it stand out that the point of
> diff3's verboseness compared to the rcs-merge output is to
> disambiguate two cases.  If you start from ABCmO and one side has
> ABMO while the other side has ACMO, the right resolution would be
> AMO (the above case I added), but if your starting point were AmO
> and the two sides ends with ABMO and ACMO respectively, the right
> resolution would be ABCMO.  The rcs-merge output does not tell you
> which is more likely to be correct, diff3 disambiguates these two
> cases by being more verbose.
>
> And telling that value of diff3 is about disambiguating is valuable
> when ...
>
>> +[NOTE]
>> +================================
>> +`zdiff3` is an alternative to `diff3` that makes the merge conflict
>> +shorter by making it more ambiguous.
>> +================================
>
> ... this note tells the readers that zdiff3 is a ambigous variant of
> diff3, hinting its flaw.