[doc] Add new page on merge conflicts - #2237

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:

>  Documentation/Makefile               |   1 +
>  Documentation/gitmergeconflicts.adoc | 294 +++++++++++++++++++++++++++
>  Documentation/meson.build            |   1 +
>  3 files changed, 296 insertions(+)
>  create mode 100644 Documentation/gitmergeconflicts.adoc
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index f8dea4b395..bc49641dda 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc
>  MAN7_TXT += giteveryday.adoc
>  MAN7_TXT += gitfaq.adoc
>  MAN7_TXT += gitglossary.adoc
> +MAN7_TXT += gitmergeconflicts.adoc

This unfortunately needs to be accompanied with a matching change to
help the other build system.

You probably want to move your change to set conflict-marker-size
for this new file to this step, not at the end as if an
afterthought.


 Documentation/meson.build | 1 +
 1 file changed, 1 insertion(+)

diff --git c/Documentation/meson.build w/Documentation/meson.build
index 51647957e0..10b0637991 100644
--- c/Documentation/meson.build
+++ w/Documentation/meson.build
@@ -201,6 +201,7 @@ manpages = {
   'giteveryday.adoc' : 7,
   'gitfaq.adoc' : 7,
   'gitglossary.adoc' : 7,
+  'gitmergeconflicts.adoc' : 7,
   'gitpacking.adoc' : 7,
   'gitmergeconflicts.adoc' : 7,
   'gitnamespaces.adoc' : 7,

Junio C Hamano <gitster@pobox.com> writes:

> This unfortunately needs to be accompanied with a matching change to
> help the other build system.

I did get a build failure due to meson, but apparently not due to
this step in the 7-patch series.

> You probably want to move your change to set conflict-marker-size
> for this new file to this step, not at the end as if an
> afterthought.

This still stands, though.

Sorry, a wrong patch and a false alarm.

>
>
>  Documentation/meson.build | 1 +
>  1 file changed, 1 insertion(+)
>
> diff --git c/Documentation/meson.build w/Documentation/meson.build
> index 51647957e0..10b0637991 100644
> --- c/Documentation/meson.build
> +++ w/Documentation/meson.build
> @@ -201,6 +201,7 @@ manpages = {
>    'giteveryday.adoc' : 7,
>    'gitfaq.adoc' : 7,
>    'gitglossary.adoc' : 7,
> +  'gitmergeconflicts.adoc' : 7,
>    'gitpacking.adoc' : 7,
>    'gitmergeconflicts.adoc' : 7,
>    'gitnamespaces.adoc' : 7,

Hi Julia,

On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Julia Evans <julia@jvns.ca>
>
> All of the info about merge conflicts has been moved to the new guide

> Among the changes made to the common ancestor's version,
> -non-overlapping ones (that is, you changed an area of the file while the
> -other side left that area intact, or vice versa) are incorporated in the
> -final result verbatim.  When both sides made changes to the same area,
> -however, Git cannot randomly pick one side over the other, and asks you to
> -resolve it by leaving what both sides did to that area.

> - * Look at the diffs from each branch. `git log --merge -p <path>`
> -   will show diffs first for the `HEAD` version and then the
> -   `MERGE_HEAD` version.

I think these are both valuable pieces of information we have lost in
the new guide (unless I misremember just having read patch 1 :).

The first explains a bit more about what a conflict *is*. Maybe that's
old-hat nowadays, but I think it could be nice to keep a statement
about why conflicts exist.

The second is a very useful way to get more context to help resolve
conflicts! I have an alias "conflict = log --oneline --graph
--left-right --boundary --merge" for a similar purpose, and I think
the new guide should help folks discover --merge. Often I can get a
better sense of how to resolve conflicts by comparing the original
changes on each side, or I might at least know who to ask about what
to do.

-- 
D. Ben Knoble

On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote:
> Hi Julia,
>
> On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>>
>> From: Julia Evans <julia@jvns.ca>
>>
>> All of the info about merge conflicts has been moved to the new guide
>
>> Among the changes made to the common ancestor's version,
>> -non-overlapping ones (that is, you changed an area of the file while the
>> -other side left that area intact, or vice versa) are incorporated in the
>> -final result verbatim.  When both sides made changes to the same area,
>> -however, Git cannot randomly pick one side over the other, and asks you to
>> -resolve it by leaving what both sides did to that area.
>
>> - * Look at the diffs from each branch. `git log --merge -p <path>`
>> -   will show diffs first for the `HEAD` version and then the
>> -   `MERGE_HEAD` version.
>
> I think these are both valuable pieces of information we have lost in
> the new guide (unless I misremember just having read patch 1 :).
>
> The first explains a bit more about what a conflict *is*. Maybe that's
> old-hat nowadays, but I think it could be nice to keep a statement
> about why conflicts exist.

Will think about this!

> The second is a very useful way to get more context to help resolve
> conflicts! I have an alias "conflict = log --oneline --graph
> --left-right --boundary --merge" for a similar purpose, and I think
> the new guide should help folks discover --merge. Often I can get a
> better sense of how to resolve conflicts by comparing the original
> changes on each side, or I might at least know who to ask about what
> to do.

Thanks, I meant to flag this: the reason I deleted it was really
just that I couldn't understand what `git log --merge -p <path>`  did
from the documentation and so I removed it until I could figure it out.
I thought that `--merge` meant that it had something to do with merge
commits, but upon further investigation it looks like that's not true, and
that `--merges` is related to merge commits, `--merge` is something
totally different which is relevant any time there's a conflict

My best guess now is that it would make sense to include this
under "Tools to get more context". Maybe something like this:

> `git log --merge -p <filename>`  will print out all commits which
>   caused the merge conflict for `<filename>`, and the diff
>  of how they changed the file. 

("which caused the merge conflict for" is a little more vague, but
I'm trying to convey the intent, and hopefully folks can look at
`man git log` if they want to know the specifics)

This does sound really useful.

"Julia Evans" <julia@jvns.ca> writes:

> Thanks, I meant to flag this: the reason I deleted it was really
> just that I couldn't understand what `git log --merge -p <path>`  did
> from the documentation and so I removed it until I could figure it out.

It looks at the index to figure out which paths we got conflicts on,
and then does "git log -p <those> <conflicted> <paths>".  You can
give a pathspec from the command line to further limit the output.

>> `git log --merge -p <filename>`  will print out all commits which
>>   caused the merge conflict for `<filename>`, and the diff
>>  of how they changed the file. 

If you _know_ which exact single file you are interested in, there
is not much you gain from the "--merge" option.  "--left-right"
option may be a lot more useful there.  It let's you see which side
of the merge gave you what changes.

> Le 25 sept. 2026 à 14:19, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> "Julia Evans" <julia@jvns.ca> writes:
> 
>> Thanks, I meant to flag this: the reason I deleted it was really
>> just that I couldn't understand what `git log --merge -p <path>`  did
>> from the documentation and so I removed it until I could figure it out.
> 
> It looks at the index to figure out which paths we got conflicts on,
> and then does "git log -p <those> <conflicted> <paths>".  You can
> give a pathspec from the command line to further limit the output.

This explanation omits the manual’s “HEAD…<other>” argument
that the merge option implies, which is important for
understanding the option and my alias ;)

> Le 25 sept. 2026 à 12:59, Julia Evans <julia@jvns.ca> a écrit :
> 
> 
> 
>> On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote:
>> Hi Julia,

[snip]

>> The second is a very useful way to get more context to help resolve
>> conflicts! I have an alias "conflict = log --oneline --graph
>> --left-right --boundary --merge" for a similar purpose, and I think
>> the new guide should help folks discover --merge. Often I can get a
>> better sense of how to resolve conflicts by comparing the original
>> changes on each side, or I might at least know who to ask about what
>> to do.
> 
> Thanks, I meant to flag this: the reason I deleted it was really
> just that I couldn't understand what `git log --merge -p <path>`  did
> from the documentation and so I removed it until I could figure it out.
> I thought that `--merge` meant that it had something to do with merge
> commits, but upon further investigation it looks like that's not true, and
> that `--merges` is related to merge commits, `--merge` is something
> totally different which is relevant any time there's a conflict
> 
> My best guess now is that it would make sense to include this
> under "Tools to get more context". Maybe something like this:
> 
>> `git log --merge -p <filename>`  will print out all commits which
>>  caused the merge conflict for `<filename>`, and the diff
>> of how they changed the file.
> 
> ("which caused the merge conflict for" is a little more vague, but
> I'm trying to convey the intent, and hopefully folks can look at
> `man git log` if they want to know the specifics)
> 
> This does sound really useful.

That reads well enough for me! Thanks. 

"Julia Evans" <julia@jvns.ca> writes:

> Like I mentioned before elsewhere it takes a super light approach to
> introducing the 3-way merge. (there is intentionally no mention
> of "since they diverged from the common ancestor" etc)
>
>     WHAT IS A MERGE CONFLICT?
>     -------------------------
>
>     When Git merges two commits together, it looks at the changes that
>     each side has made and combines those changes. For example, if one side
>     edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
>     `hello.py`, then it can easily combine them.

Some immediate reactions.

 - Is it obvious that the reason why it can "easily combine" them,
   or would it help to be more explicit (i.e., "as there is no
   overlap")?

 - The second "of `hello.py`" forced me to go back and look at the
   first one again to make sure we are talking about the same file.
   I would imagine if the latter were "lines 20-25 of the same file",
   it would have read better at least to me.

>     But if both sides edited overlapping lines of the same file (for example
>     one side edited lines 1-5 and the other edited lines 3-6), Git will
>     not try to guess how to combine those changes. This is called a "merge
>     conflict".

 - "cannot guess" would be more direct than "will not try to guess".

>     When this happens, Git shows you both sides' edits and asks you to pick
>     how to resolve them. It:
>
>     * Stages all of the files which were successfully merged

 - "merged without conflicts" would be more direct than "successfully merged".

>     * For the files with conflicts, it leaves them unstaged, puts both
>       sides' edits in the file, and leaves <<markers, merge conflict markers>>
>       that you need to resolve.

 - "unstaged" sounds as if somebody ran "git rm --cached" on the
   paths, but that is not what you want to tell your readers.

 - "it leaves them unstaged" -> "it remembers them as conflicted",
   perhaps?  This hints that Git has a mechanism to remember the
   conflicted paths even after you removed the conflict markers from
   the file to your readers.

>>     WHAT IS A MERGE CONFLICT?
>>     -------------------------
>>
>>     When Git merges two commits together, it looks at the changes that
>>     each side has made and combines those changes. For example, if one side
>>     edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
>>     `hello.py`, then it can easily combine them.
>
> Some immediate reactions.

Thanks, incorporated a few of these ("it marks them as conflicted",
"since there's no overlap", "the same file")

>>     But if both sides edited overlapping lines of the same file (for example
>>     one side edited lines 1-5 and the other edited lines 3-6), Git will
>>     not try to guess how to combine those changes. This is called a "merge
>>     conflict".
>
>  - "cannot guess" would be more direct than "will not try to guess".

The way I think about it as a user is that Git takes an intentionally conservative
approach and I appreciate the conservatism. Compared to a more aggressive
syntax-aware merge system like `mergiraf` which has done merges I don't
agree with.

"Julia Evans" <julia@jvns.ca> writes:

>>  - "cannot guess" would be more direct than "will not try to guess".
>
> The way I think about it as a user is that Git takes an intentionally conservative
> approach and I appreciate the conservatism. Compared to a more aggressive
> syntax-aware merge system like `mergiraf` which has done merges I don't
> agree with.

Your disagreement with their result suggests that they guessed when
they could not do so reliably.  I agree that our approach is more
conservative, but we can call it being more honest.

;-).

On Fri, Oct 2, 2026 at 1:01 PM Julia Evans <julia@jvns.ca> wrote:
>
>
>
> On Fri, Sep 25, 2026, at 12:59 PM, Julia Evans wrote:
> > On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote:
> >> Hi Julia,
> >>
> >> On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget
> >> <gitgitgadget@gmail.com> wrote:
> >>>
> >>> From: Julia Evans <julia@jvns.ca>
> >>>
> >>> All of the info about merge conflicts has been moved to the new guide
> >>
> >>> Among the changes made to the common ancestor's version,
> >>> -non-overlapping ones (that is, you changed an area of the file while the
> >>> -other side left that area intact, or vice versa) are incorporated in the
> >>> -final result verbatim.  When both sides made changes to the same area,
> >>> -however, Git cannot randomly pick one side over the other, and asks you to
> >>> -resolve it by leaving what both sides did to that area.
>
> >> I think these are both valuable pieces of information we have lost in
> >> the new guide (unless I misremember just having read patch 1 :).
> >>
> >> The first explains a bit more about what a conflict *is*. Maybe that's
> >> old-hat nowadays, but I think it could be nice to keep a statement
> >> about why conflicts exist.
> >
> > Will think about this!
>
> After talking this through with my collaborator Marie, we wrote a new
> "what is a merge conflict?" section which I'll include in the v2.
>
> Like I mentioned before elsewhere it takes a super light approach to
> introducing the 3-way merge. (there is intentionally no mention
> of "since they diverged from the common ancestor" etc)
>
>     WHAT IS A MERGE CONFLICT?
>     -------------------------
>
>     When Git merges two commits together, it looks at the changes that
>     each side has made and combines those changes. For example, if one side
>     edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
>     `hello.py`, then it can easily combine them.
>
>     But if both sides edited overlapping lines of the same file (for example
>     one side edited lines 1-5 and the other edited lines 3-6), Git will
>     not try to guess how to combine those changes. This is called a "merge
>     conflict".
>
>     When this happens, Git shows you both sides' edits and asks you to pick
>     how to resolve them. It:
>
>     * Stages all of the files which were successfully merged
>     * For the files with conflicts, it leaves them unstaged, puts both
>       sides' edits in the file, and leaves <<markers, merge conflict markers>>
>       that you need to resolve.
>

I quite like this. I'm sure it oversimplifies somewhere, but at least
I personally cannot immediately see where (or how it does any harm to)
;)

Thanks!

PS Unlike Junio---perhaps due to my lack of older Git history and
terminology, despite using Git since 2016?---I would never have read
"unstaged" as *deleted* from the index. Just changed and not updated
in the index (i.e., not "git add"-ed).

-- 
D. Ben Knoble

"D. Ben Knoble" <ben.knoble@gmail.com> writes:

> PS Unlike Junio---perhaps due to my lack of older Git history and
> terminology, despite using Git since 2016?---I would never have read
> "unstaged" as *deleted* from the index. Just changed and not updated
> in the index (i.e., not "git add"-ed).

I agree such an interpretation is certainly possible.

The verb "to unstage" would be the opposite of "to stage", but it is
ambiguous what kind of oppositeness you want to express.  This is
unlike "to stage" whose possible interpretation is fairly narrow.
You register the contents that you consider desirable for the path
using various means.  On the other hand, "to unstage" is undoing the
result of your earlier act "to stage", but it may mean reverting to
what is recorded in HEAD (i.e., "git reset HEAD -- path"), undoing
the fact that you added a path to the index (i.e., "git rm --cached
-- path").  Neither interpretation is what you want when talking
about what a conflicted merge does to remember the three stages for
a conflicted path in the index.

Hence my suggestion to avoid using the verb.

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

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

> +[NOTE]
> +================================
> +Even if Git successfully merges both sides with no conflicts, it's
> +possible to end up with code that doesn't work. For example, this can
> +happen if one side renames a function, and the other side adds a call to
> +the old function. This is called a "semantic merge conflict".
> +================================

OK.

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

The only thing you can say from the sample output below is in the
current state "one side has cherry where the other side has banana,
and everything else is the same".  You cannot say more without
seeing diff3 style conflict.

> +----
> +FRUITS = [
> +    "apple",
> +<<<<<<< HEAD
> +    "cherry",
> +=======
> +    "banana",
> +>>>>>>> add-fruit
> +    "mango",
> +    "orange",
> +]
> +----
> +
> +The code from one side of the merge conflict is between `<<<<<<<` and
> +`=======`, and the code for the other side is between `=======` and
> +`>>>>>>>`. See <<ours,"OURS" AND "THEIRS">> below for a full explanation
> +of which side is which.




> +[[example]]
> +EXAMPLE OF RESOLVING A MERGE CONFLICT
> +-------------------------------------
> +
> +If you see this in your code during a merge conflict:
> +
> +----
> +FRUITS = [
> +    "apple",
> +<<<<<<< HEAD
> +    "cherry",
> +=======
> +    "banana",
> +>>>>>>> add-fruit
> +    "mango",
> +    "orange",
> +]
> +----
> +
> +Then you might edit that part of the code like this,
> +which includes the fruits from both sides of the conflict:
> +
> +----
> +FRUITS = [
> +    "apple",
> +    "banana",
> +    "cherry",
> +    "mango",
> +    "orange",
> +]
> +----

So, this is one possible resolution.  We cannot tell if it is the
correct one.

> +[[tools]]
> +TOOLS FOR HANDLING MERGE CONFLICTS
> +----------------------------------
> +
> +Here are some ways to get extra context while handling a merge conflict:
> ...

The incremental changes to this list looks good.

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

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.

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.

"Julia Evans" <julia@jvns.ca> writes:

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

I do not quite follow.  "apply -3" is making a 3-way merge among the
state _your_ working tree is in, the state shown as the preimage in
the patch (i.e., before the patch author had the change they gave
you in the patch), and the state shown as the postimage in the patch
(i.e., after the patch author made the change).

It is no different from the case where cherry-picking the change the
patch author had stopped in conflict if (1) the machinery did find
the necessary preimage blobs and (2) the 3way application did stop
in a conflict.

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

Thanks.

On Mon, Oct 12, 2026 at 02:53:10PM +0000, Julia Evans via GitGitGadget wrote:
> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
> new file mode 100644
> index 0000000000..3c6eaaddf8
> --- /dev/null
> +++ b/Documentation/gitmergeconflicts.adoc
> @@ -0,0 +1,330 @@
> +gitmergeconflicts(7)
> +====================
> +
> +NAME
> +----
> +gitmergeconflicts - Guide to handling merge conflicts
> +
> +DESCRIPTION
> +-----------
> +
> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
> +cherry-pick`, `git pull`, `git revert`, or any other command that does
> +a merge. All of those commands use the same merge algorithm, and the
> +process for resolving a merge conflict is always very similar.
> +
> +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

Nit: the punctuation is a bit inconsistent, where the second bullet
point has a trailing punctuation mark but the other two don't.

> +WHAT IS A MERGE CONFLICT?
> +-------------------------
> +
> +When Git merges two commits together, it looks at the changes that
> +each side has made and combines those changes. For example, if one side
> +edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
> +the same file, then it can easily combine them since there's no overlap.
> +
> +But if both sides edited overlapping lines of the same file (for example
> +one side edited lines 1-5 and the other edited lines 3-6), Git will
> +not try to guess how to combine those changes. This is called a "merge
> +conflict".
> +
> +When this happens, Git shows you both sides' edits and asks you to pick
> +how to resolve them. It:
> +
> +* Stages all of the files which were successfully merged
> +* For the files with conflicts, it marks them as conflicted, puts both
> +  sides' edits in the file, and leaves <<markers, merge conflict markers>>
> +  that you need to resolve.

Same nit here.

> +[NOTE]
> +================================
> +Even if Git successfully merges both sides with no conflicts, it's
> +possible to end up with code that doesn't work. For example, this can
> +happen if one side renames a function, and the other side adds a call to
> +the old function. This is called a "semantic merge conflict".
> +================================

Good callout. We may also want to spell out the consequence of this:
"You should always verify the result of a merge regardless of whether or
not it has resulted in a conflict.".

> +[[resolve]]
> +HOW TO RESOLVE A MERGE CONFLICT
> +-------------------------------
> +
> +The process for resolving a merge conflict is:
> +
> +1. Run `git status` to get a list of files with merge conflicts
> +2. For each one, find the conflict markers
> +   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to
> +   fix the conflict
> +3. Run `git add FILENAME` for each file to mark the conflict as resolved
> +4. Run the appropriate `--continue` command to continue the operation
> +   that was interrupted by the conflict, for example `git merge --continue`
> +   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>
> +   below for how to find the command to run.

Same nit regarding punctuation. Or is this actually a thing, where you
add punctuation in case it's multiple sentences but not in the case
where it's a single sentence, only? Maybe this is just me not being a
native speaker.

> +[[tools]]
> +TOOLS FOR HANDLING MERGE CONFLICTS
> +----------------------------------
> +
> +Here are some ways to get extra context while handling a merge conflict:
> +
> +* There are many graphical "merge tools" for Git, which will normally
> +  show you the different versions of the code side by side.
> +  If you have a mergetool configured, `git mergetool` will launch it.
> +  See also `merge.tool` in linkgit:git-config[1] for a list of
> +  the mergetools Git supports.
> +
> +* You can set the configuration variable `merge.conflictstyle=diff3`.
> +  See <<diff3,DIFF3>> below for more.
> +
> +* `git log --merge -p <filename>`  will list all commits which

Should we spell this out as `--patch` instead? That's way easier to grep
in the manpage in case the reader is curious what the option does.

> +[NOTE]
> +================================
> +`zdiff3` is an alternative to `diff3` that makes the merge conflict
> +shorter by making it more ambiguous.
> +================================

"making it more ambiguous" reads rather curious. Should we maybe take
inspiration from its documentation and instead say "by removing matching
lines on the two sides from the beginning or end of a conflict region"?

> +[[ours]]
> +"OURS" AND "THEIRS"
> +-------------------
> +
> +Sometimes during a merge conflict, Git will use the terms "ours" and
> +"theirs" (or "us" and "them"). For example, `git status` might say that
> +a file was `deleted by us`.
> +
> +"Ours" and "theirs" are both commits: "ours" is the current
> +`HEAD` commit, and "theirs" is the other side being merged.

They may not always be commits, but they are always tree-ishs. But I
think it's fine to leave this as-is anyway, as the normal user is never
going to encounter cases where it's not in fact a commit. And when they
do they probably don't need this manpage anyway.

Other than this handful of nits I'm happy with this version, thanks!

Patrick

On Tue, Oct 13, 2026, at 7:07 AM, Patrick Steinhardt wrote:
> On Mon, Oct 12, 2026 at 02:53:10PM +0000, Julia Evans via GitGitGadget wrote:
>> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
>> new file mode 100644
>> index 0000000000..3c6eaaddf8
>> --- /dev/null
>> +++ b/Documentation/gitmergeconflicts.adoc
>> @@ -0,0 +1,330 @@
>> +gitmergeconflicts(7)
>> +====================
>> +
>> +NAME
>> +----
>> +gitmergeconflicts - Guide to handling merge conflicts
>> +
>> +DESCRIPTION
>> +-----------
>> +
>> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
>> +cherry-pick`, `git pull`, `git revert`, or any other command that does
>> +a merge. All of those commands use the same merge algorithm, and the
>> +process for resolving a merge conflict is always very similar.
>> +
>> +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
>
> Nit: the punctuation is a bit inconsistent, where the second bullet
> point has a trailing punctuation mark but the other two don't.

Thanks, tried to make this a bit more consistent. I think I have some slightly
idiosyncratic personal rules for punctuation in bulleted lists that I don't
feel very attached to.

>> +WHAT IS A MERGE CONFLICT?
>> +-------------------------
>> +
>> +When Git merges two commits together, it looks at the changes that
>> +each side has made and combines those changes. For example, if one side
>> +edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of
>> +the same file, then it can easily combine them since there's no overlap.
>> +
>> +But if both sides edited overlapping lines of the same file (for example
>> +one side edited lines 1-5 and the other edited lines 3-6), Git will
>> +not try to guess how to combine those changes. This is called a "merge
>> +conflict".
>> +
>> +When this happens, Git shows you both sides' edits and asks you to pick
>> +how to resolve them. It:
>> +
>> +* Stages all of the files which were successfully merged
>> +* For the files with conflicts, it marks them as conflicted, puts both
>> +  sides' edits in the file, and leaves <<markers, merge conflict markers>>
>> +  that you need to resolve.
>
> Same nit here.

>> +[NOTE]
>> +================================
>> +Even if Git successfully merges both sides with no conflicts, it's
>> +possible to end up with code that doesn't work. For example, this can
>> +happen if one side renames a function, and the other side adds a call to
>> +the old function. This is called a "semantic merge conflict".
>> +================================
>
> Good callout. We may also want to spell out the consequence of this:
> "You should always verify the result of a merge regardless of whether or
> not it has resulted in a conflict.".

I think we should let people use their own judgment about how to use this
information.

>> +[[resolve]]
>> +HOW TO RESOLVE A MERGE CONFLICT
>> +-------------------------------
>> +
>> +The process for resolving a merge conflict is:
>> +
>> +1. Run `git status` to get a list of files with merge conflicts
>> +2. For each one, find the conflict markers
>> +   (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to
>> +   fix the conflict
>> +3. Run `git add FILENAME` for each file to mark the conflict as resolved
>> +4. Run the appropriate `--continue` command to continue the operation
>> +   that was interrupted by the conflict, for example `git merge --continue`
>> +   or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>
>> +   below for how to find the command to run.
>
> Same nit regarding punctuation. Or is this actually a thing, where you
> add punctuation in case it's multiple sentences but not in the case
> where it's a single sentence, only? Maybe this is just me not being a
> native speaker.
>
>> +[[tools]]
>> +TOOLS FOR HANDLING MERGE CONFLICTS
>> +----------------------------------
>> +
>> +Here are some ways to get extra context while handling a merge conflict:
>> +
>> +* There are many graphical "merge tools" for Git, which will normally
>> +  show you the different versions of the code side by side.
>> +  If you have a mergetool configured, `git mergetool` will launch it.
>> +  See also `merge.tool` in linkgit:git-config[1] for a list of
>> +  the mergetools Git supports.
>> +
>> +* You can set the configuration variable `merge.conflictstyle=diff3`.
>> +  See <<diff3,DIFF3>> below for more.
>> +
>> +* `git log --merge -p <filename>`  will list all commits which
>
> Should we spell this out as `--patch` instead? That's way easier to grep
> in the manpage in case the reader is curious what the option does.

Good idea, will do.

>> +[NOTE]
>> +================================
>> +`zdiff3` is an alternative to `diff3` that makes the merge conflict
>> +shorter by making it more ambiguous.
>> +================================
>
> "making it more ambiguous" reads rather curious. Should we maybe take
> inspiration from its documentation and instead say "by removing matching
> lines on the two sides from the beginning or end of a conflict region"?

Hmm, I've gone back and forth a lot on how to explain zdiff3, from

1. Here's how it works and here's an example to illustrate
2. You shouldn't use it
3. You may want to use it but be aware that it's ambiguous
4. Here's more info about about how it works

I think Junio's diff3 example does a really good job of making it clear 
why diff3 might be useful. The previous zdiff3 example I had that talked
about the pros and cons of using zdiff3 didn't feel very compelling to me
and I don't know how to write a good one. I think a good example
probably does exist, but we might actually need multiple examples
(both to show how zdiff can be useful and to show the issues).

Perhaps given that we seem to not necessarily want to recommend
zdiff3, we can just not mention zdiff3 for now and add it back later if/when
we feel more confident about how to explain it. I'll try just deleting the note.

>> +[[ours]]
>> +"OURS" AND "THEIRS"
>> +-------------------
>> +
>> +Sometimes during a merge conflict, Git will use the terms "ours" and
>> +"theirs" (or "us" and "them"). For example, `git status` might say that
>> +a file was `deleted by us`.
>> +
>> +"Ours" and "theirs" are both commits: "ours" is the current
>> +`HEAD` commit, and "theirs" is the other side being merged.
>
> They may not always be commits, but they are always tree-ishs. But I
> think it's fine to leave this as-is anyway, as the normal user is never
> going to encounter cases where it's not in fact a commit. And when they
> do they probably don't need this manpage anyway.

Interesting, I didn't know it could be something other than a commit.

>
> Other than this handful of nits I'm happy with this version, thanks!
>
> Patrick

thanks for the review!

On Mon, Oct 12, 2026 at 02:53:14PM +0000, Julia Evans via GitGitGadget wrote:
> From: Julia Evans <julia@jvns.ca>
> 
> Remove the discussion of merge conflicts and replace it with a link to
> the guide.

Nit: you don't really change the discussion anymore, so this commit
message is inaccurate by now.

Patrick