[doc] Add new page on merge conflicts

[jvns]

Handling merge conflicts is difficult, and currently Git's guidance on merge conflicts isn't giving users the information they need to navigate the process. As usual, the process I used to write this was to collect comments from Git users on the existing documentation, and then address those issues. I listed the specific issues we're aiming to solve in the first commit message in the series.

This patch series introduces a new manual page, gitmergeconflicts, which explains the process of explaining a merge conflict with examples. It also links to that new page from the commands which can cause merge conflicts, instead of trying to reexplain the process every time.

This is a pretty big change, so here's a list of things I'm still considering in the hopes that it'll help with the discussion:

• I wrote that git commit does the same thing as git merge --continue during a git merge , but I'm not sure if that's always true.
• Not 100% sure that the explanation of diff3 vs zdiff3 is correct
• Right now we're listing git merge, git revert, git rebase, git cherry-pick, and git pull as commands that can cause merge conflicts. I believe that git apply and git am can also result in conflicts when applying a patch, though it's a bit complicated because applying a patch is a different operation than doing a 3-way merge and the tools available for dealing with it are a different. My thought right now is to avoid the issue of applying patches for now (because it's a whole can of worms) and instead just try to not imply that this is necessarily an exhaustive list. Also if/when the git rebase --squash changes land, then we'd need to add git history to this list.
• Instead of creating a new page, I considered using an include to have a "handling merge conflicts" section in git rebase, git merge, etc. Merge conflict resolution is complex and it's very useful to be able to include examples: this version ended up at ~300 lines and I think that's too big of an include, especially for short man pages like cherry-pick
• Explaining what "ours" and "theirs" mean was one of the hardest parts of writing this. From polling Git users in one of my many informal Mastodon polls about Git, my understanding is that Git users are actually relatively unlikely to actually reason about what "ours" and "theirs" mean when dealing with a merge conflict, and that most people prefer to get more context instead, for example by using a mergetool or by using diff3 or zdiff3. I heard a lot of "I can never remember which is which I so I don't even try". So I put the information about what "ours" and "theirs" mean relatively far down the page (with some cross-references), so that it's easily available but not the main focus.
• I removed a couple of mentions of the various _HEAD references. It's hard for me to know exactly where they belong because I personally have never used MERGE_HEAD, REBASE_HEAD, ORIG_HEAD, CHERRY_PICK_HEAD etc, and I don't know how they're meant to be used. From some quick unscientific polling (at https://social.jvns.ca/@b0rk/117320011885941855), it seems like most Git users have never used them either (and folks who do use a *_HEAD reference mainly seem to use FETCH_HEAD which isn't relevant here), so from that perspective it seems important to avoid emphasizing them too much. The git revert man page doesn't mention REVERT_HEAD and git rebase only mentions REBASE_HEAD in passing. Of course they're all explained in gitrevisions(7) which might be the best place for them.
• I'm still not sure what the SYNOPSIS section is for in a "guide" man page which is not about a specific Git command (what is the user intended to use it for?). I tried to leave it out but the CI said it was required.

Thanks to Lobo, Adam Svahn, Louis Vanier, David Turner, Ben Zanin, Salih, and about 12 others who gave feedback on both the original git merge man page, as well as the proposed improvements.

CC: ps@pks.im
cc: Jeff King peff@peff.net
cc: "D. Ben Knoble" ben.knoble@gmail.com

[gitgitgadget]

There is an issue in commit 7dee697:
[doc] Add new gitmergeconflicts man page

• Commit not signed off

[gitgitgadget]

There is an issue in commit 3a9e01d:
[doc] git-merge: link to new merge conflicts guide

• Commit not signed off

[gitgitgadget]

There is an issue in commit c96ce90:
[doc] git-rebase: link to new merge conflicts guide

• Commit not signed off

[gitgitgadget]

There are issues in commit a340474:
[doc] git-revert: link to new merge conflicts guide

• Commit checks stopped - the message is too short
• Commit not signed off

[gitgitgadget]

There is an issue in commit 67302e7:
[doc] git-cherry-pick: link to new merge conflicts guide

• Commit not signed off

[gitgitgadget]

There are issues in commit 241bf3e:
[doc] git-pull: link to new merge conflicts guide

• Commit checks stopped - the message is too short
• Commit not signed off

[jvns]

The check_whitespace job is failing because of merge conflict markers, but the reason there are merge conflict markers is that we're documenting how to handle merge conflicts. Not sure what to do about that.

(edit: I think it's in .gitattributes)

[dscho]

The check_whitespace job is failing because of merge conflict markers, but the reason there are merge conflict markers is that we're documenting how to handle merge conflicts.

Yep: see e.g. https://github.com/git/git/blob/v2.55.0/.gitattributes#L16

[jvns]

Not sure what's going on with the debian-12 test failure but I'm planning to ignore it for now.

[dscho]

Not sure what's going on with the debian-12 test failure but I'm planning to ignore it for now.

@jvns see here: #2236. You can safely ignore it.

[jvns]

thanks, appreciate your work on testing!

[jvns]

/preview

[gitgitgadget]

Preview email sent as pull.2237.git.1790185498.gitgitgadget@gmail.com

[jvns]

/submit

[gitgitgadget]

Submitted as pull.2237.git.1790261062.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

git fetch https://github.com/gitgitgadget/git/ pr-2237/jvns/merge-conflicts-v1

To fetch this version to local tag pr-2237/jvns/merge-conflicts-v1:

git fetch --no-tags https://github.com/gitgitgadget/git/ tag pr-2237/jvns/merge-conflicts-v1

[gitgitgadget]

This patch series was integrated into seen via git@a459886.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

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

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

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,

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

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

> Julia Evans (7):
>   [doc] Add new gitmergeconflicts man page
>   [doc] git-merge: link to new merge conflicts guide
>   [doc] git-rebase: link to new merge conflicts guide
>   [doc] git-revert: link to new merge conflicts guide
>   [doc] git-cherry-pick: link to new merge conflicts guide
>   [doc] git-pull: link to new merge conflicts guide
>   [doc] ignore conflict markers in gitmergeconflicts.adoc

With this merged, 'seen' seems to fail

	$ make check-docs

with these lines at the end

            ...
            MKDIR -p .build/lint-docs/doc-style/includes
            LINT DOCSTYLE includes/cmd-config-section-all.adoc
            LINT DOCSTYLE includes/cmd-config-section-rest.adoc
            GEN lint-docs-manpages
        no link: gitmergeconflicts

Thanks.

[gitgitgadget]

Jeff King wrote on the Git mailing list (how to reply to this email):

On Thu, Sep 24, 2026 at 03:20:30PM -0700, Junio C Hamano wrote:

> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> > Julia Evans (7):
> >   [doc] Add new gitmergeconflicts man page
> >   [doc] git-merge: link to new merge conflicts guide
> >   [doc] git-rebase: link to new merge conflicts guide
> >   [doc] git-revert: link to new merge conflicts guide
> >   [doc] git-cherry-pick: link to new merge conflicts guide
> >   [doc] git-pull: link to new merge conflicts guide
> >   [doc] ignore conflict markers in gitmergeconflicts.adoc
> 
> With this merged, 'seen' seems to fail
> 
> 	$ make check-docs
> 
> with these lines at the end
> 
>             ...
>             MKDIR -p .build/lint-docs/doc-style/includes
>             LINT DOCSTYLE includes/cmd-config-section-all.adoc
>             LINT DOCSTYLE includes/cmd-config-section-rest.adoc
>             GEN lint-docs-manpages
>         no link: gitmergeconflicts

Weirdly applying Julia's patches myself did not result in the same
error. It's only when they're merged to seen. Ah. It's due to
ta/command-list-guides-sync-lint, which isn't yet in master.

I think that is giving us a good signal, though. The guide should be
mentioned in command-list.txt, so that it is linked from git(1). See
c655855559 (doc: git: list gitdatamodel(7) as a concept guide,
2026-09-05) for some prior art.

-Peff

[gitgitgadget]

User Jeff King <peff@peff.net> has been added to the cc: list.

[gitgitgadget]

"D. Ben Knoble" wrote on the Git mailing list (how to reply to this email):

A big thank you for working on this.

On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> Handling merge conflicts is difficult, and currently Git's guidance on merge
> conflicts isn't giving users the information they need to navigate the
> process. As usual, the process I used to write this was to collect comments
> from Git users on the existing documentation, and then address those issues.
> I listed the specific issues we're aiming to solve in the first commit
> message in the series.
>
> This patch series introduces a new manual page, gitmergeconflicts, which
> explains the process of explaining a merge conflict with examples. It also
> links to that new page from the commands which can cause merge conflicts,
> instead of trying to reexplain the process every time.
>
> This is a pretty big change, so here's a list of things I'm still
> considering in the hopes that it'll help with the discussion:
>
>  * I wrote that git commit does the same thing as git merge --continue
>    during a git merge , but I'm not sure if that's always true.

See also discussion in
https://lore.kernel.org/git/CABPp-BEQSx4m3BcT28CpVGCtsH75+x3gmv4OJz_ecLVLx+kBWg@mail.gmail.com/T/#t

>  * Right now we're listing git merge, git revert, git rebase, git
>    cherry-pick, and git pull as commands that can cause merge conflicts. I
>    believe that git apply and git am can also result in conflicts when
>    applying a patch, though it's a bit complicated because applying a patch
>    is a different operation than doing a 3-way merge and the tools available
>    for dealing with it are a different. My thought right now is to avoid the
>    issue of applying patches for now (because it's a whole can of worms) and
>    instead just try to not imply that this is necessarily an exhaustive
>    list.

I think that's a good approach!

> Also if/when the git rebase --squash changes land, then we'd need
>    to add git history to this list.

I imagine you meant history squash? I also thought that history had
punted on how to deal with conflicts (rejecting any operation which
creates them) for now, since we don't have 1st-class conflicts à la
Jujutsu.

>  * Instead of creating a new page, I considered using an include to have a
>    "handling merge conflicts" section in git rebase, git merge, etc. Merge
>    conflict resolution is complex and it's very useful to be able to include
>    examples: this version ended up at ~300 lines and I think that's too big
>    of an include, especially for short man pages like cherry-pick

Sensible. I have often wished some of our includes were actually links
to separate documents, to keep overall document size down.

>  * Explaining what "ours" and "theirs" mean was one of the hardest parts of
>    writing this. From polling Git users in one of my many informal Mastodon
>    polls about Git, my understanding is that Git users are actually
>    relatively unlikely to actually reason about what "ours" and "theirs"
>    mean when dealing with a merge conflict, and that most people prefer to
>    get more context instead, for example by using a mergetool or by using
>    diff3 or zdiff3. I heard a lot of "I can never remember which is which I
>    so I don't even try". So I put the information about what "ours" and
>    "theirs" mean relatively far down the page (with some cross-references),
>    so that it's easily available but not the main focus.

I think the biggest reason to (ahem) reason about these is if one
wants to restore --{ours,theirs} or restart and try again with a merge
strategy -s {ours,theirs} [rare] or merge strategy option -X
{ours,theirs} [less rare].

But, leaving it out of focus makes sense to me!

>  * I removed a couple of mentions of the various _HEAD references. It's hard
>    for me to know exactly where they belong because I personally have never
>    used MERGE_HEAD, REBASE_HEAD, ORIG_HEAD, CHERRY_PICK_HEAD etc, and I
>    don't know how they're meant to be used.

My most frequently use is "git show REBASE_HEAD" (which is what "git
rebase --show-current-patch" does, albeit with more typing). :shrug:

-- 
D. Ben Knoble

[gitgitgadget]

User "D. Ben Knoble" <ben.knoble@gmail.com> has been added to the cc: list.

[gitgitgadget]

"D. Ben Knoble" wrote on the Git mailing list (how to reply to this email):

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

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

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.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

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

[gitgitgadget]

Ben Knoble wrote on the Git mailing list (how to reply to this email):

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

[gitgitgadget]

Ben Knoble wrote on the Git mailing list (how to reply to this email):

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

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

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

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

Ahh, yes, you're right.  HEAD...MERGE_HEAD is the more important
half of what --merge gives us that I failed to mention.

And without the symmetric difference traversal it gives,
--left-right would of course not work, either.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

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

> From: Julia Evans <julia@jvns.ca>
>
> Remove the discussion of merge conflicts and replace it with a link to
> the guide.
>
> Signed-off-by: Julia Evans <julia@jvns.ca>
> ---
>  Documentation/git-cherry-pick.adoc | 23 ++++-------------------
>  1 file changed, 4 insertions(+), 19 deletions(-)
>
> diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc
> index f4cd8b9db7..d93829600b 100644
> --- a/Documentation/git-cherry-pick.adoc
> +++ b/Documentation/git-cherry-pick.adoc
> @@ -19,25 +19,9 @@ Given one or more existing commits, apply the change each one
>  introduces, recording a new commit for each.  This requires your
>  working tree to be clean (no modifications from the HEAD commit).
>  
> -When it is not obvious how to apply a change, the following
> -happens:
> -
> -1. The current branch and `HEAD` pointer stay at the last commit
> -   successfully made.
> -2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that
> -   introduced the change that is difficult to apply, unless the
> -   `--no-commit` option was given.
> -3. Paths in which the change applied cleanly are updated both
> -   in the index file and in your working tree.
> -4. For conflicting paths, the index file records up to three
> -   versions, as described in the "TRUE MERGE" section of
> -   linkgit:git-merge[1].  The working tree files will include
> -   a description of the conflict bracketed by the usual
> -   conflict markers `<<<<<<<` and `>>>>>>>`.
> -5. No other modifications are made.
> -
> -See linkgit:git-merge[1] for some hints on resolving such
> -conflicts.
> +When it is not obvious how to apply a change, there may
> +be a merge conflict. See linkgit:gitmergeconflicts[7]
> +(or `git help mergeconflicts`) for a guide to handling merge conflicts.

The new document may explain how to resolve conflicts, but are the
details removed from here that are specific to the 'cherry-pick'
operation also covered there?

For example, during a difficult cherry-pick, it is often handy to be
able to run 'git show CHERRY_PICK_HEAD', but now users are not told
about the pseudo-ref, which seems like a real loss.

The fact that cleanly auto-resolved contents for paths are recorded
in the index may be shared with all other merge-like operations,
and it need not be part of the "how to resolve a conflicted
merge-like operation" recipe, but users need to be assured that this
is what happens somewhere in the documentation set.  The list
removed here served that purpose for this specific command, but it
is now gone.

I do not recall offhand whether we explicitly tell our users that
all merge-like operations update the index with cleanly auto-resolved
results and only leave conflicts to be hand-resolved by the user,
but even if we did so elsewhere, I do not see any reference to that
in the existing text of the 'cherry-pick' manual, nor does this
patch series add such a link.  At least item #2 and #3 should be
kept in the list, I think.  A better alternative might be to add
your new reference, and shorten the description given in item #4,
and leave everything else as before.

Thanks.

>  
>  OPTIONS
>  -------
> @@ -259,6 +243,7 @@ $ git cherry-pick -Xpatience topic^  <4>
>  SEE ALSO
>  --------
>  linkgit:git-revert[1]
> +linkgit:gitmergeconflicts[7]
>  
>  GIT
>  ---

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

> The new document may explain how to resolve conflicts, but are the
> details removed from here that are specific to the 'cherry-pick'
> operation also covered there?

I'll update this series to make fewer changes to this page as you
suggest to make the diff smaller.

> For example, during a difficult cherry-pick, it is often handy to be
> able to run 'git show CHERRY_PICK_HEAD', but now users are not told
> about the pseudo-ref, which seems like a real loss.

I'll put this back for now, but I removed it because I couldn't
understand why CHERRY_PICK_HEAD might be useful, and some of my user research
showed that almost nobody uses `CHERRY_PICK_HEAD`. I always appreciate people
telling me why these things are actually useful though, and even if very few
people use something, maybe more people would use it if it was clear why it's
useful :)

My best guess (based on what you said) is that `CHERRY_PICK_HEAD` is
only useful if you're cherry-picking multiple commits at the same time.
Is the following an accurate explanation?:

> If the conflict happened when cherry picking multiple commits, you can run
> `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply.



> The fact that cleanly auto-resolved contents for paths are recorded
> in the index may be shared with all other merge-like operations,
> and it need not be part of the "how to resolve a conflicted
> merge-like operation" recipe, but users need to be assured that this
> is what happens somewhere in the documentation set.  The list
> removed here served that purpose for this specific command, but it
> is now gone.

That makes sense to me. One major benefit of making a
centralized page is that each man page explains different aspects
of the merge conflict process, and we can make sure that anyone
who needs to solve a merge conflict is aware of all the aspects. 
I'll think about how to explain that.

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

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

> My best guess (based on what you said) is that `CHERRY_PICK_HEAD` is
> only useful if you're cherry-picking multiple commits at the same time.
> Is the following an accurate explanation?:
>
>> If the conflict happened when cherry picking multiple commits, you can run
>> `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply.

You do not have to limit yourself to the multi-pick case.  If you
make it a habit to use CHERRY_PICK_HEAD, you do not have to remember
exactly which commit you specified on the command line to pick when
stopped by a conflict during a cherry-pick.  This is especially true
for those who have already made it a habit to use MERGE_HEAD when
stopped by a conflict during a merge.  Not having to think when you
can mechanically perform a routine task is bliss.

[gitgitgadget]

This branch is now known as je/doc-merge-conflicts.

[gitgitgadget]

This patch series is no longer integrated into seen.

[gitgitgadget]

There was a status update in the "Cooking" section about the branch je/doc-merge-conflicts on the Git mailing list:

A new gitmergeconflicts(7) manual page has been added to provide a
centralized guide for understanding and resolving merge conflicts.
The documentation for commands that generate conflicts (like 'git
merge', 'git rebase', and 'git cherry-pick') has been updated to
link to this new guide instead of duplicating the instructions.

Waiting for response.
cf. <xmqqo6dmz4p2.fsf@gitster.g>
cf. <20260924233726.GB765100@coredump.intra.peff.net>
cf. <xmqqpky1uu6t.fsf@gitster.g>
source: <pull.2237.git.1790261062.gitgitgadget@gmail.com>

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

> I think that is giving us a good signal, though. The guide should be
> mentioned in command-list.txt, so that it is linked from git(1).

Thanks, will fix this (and will move the conflict-marker-size change).

Should I be trying to apply my patches to `seen` before submitting them?

- Julia

[gitgitgadget]

Jeff King wrote on the Git mailing list (how to reply to this email):

On Mon, Sep 28, 2026 at 04:41:54PM -0400, Julia Evans wrote:

> > I think that is giving us a good signal, though. The guide should be
> > mentioned in command-list.txt, so that it is linked from git(1).
> 
> Thanks, will fix this (and will move the conflict-marker-size change).
> 
> Should I be trying to apply my patches to `seen` before submitting them?

In general, no, you don't have to. In this case it turned up useful
information for changing your series, but that's rare. The more likely
outcome is that there's nothing to be changed in your series, but
there's a conflict (either textual or semantic) between two topics that
has to be resolved by the maintainer.

Of course if you know about that conflict and can warn people in the
cover letter (and sometimes even suggest a resolution, or work around it
somehow), that can distribute some of the load. But I don't know that I
would recommend for everyone to manually merge their topic to 'seen' in
the hopes that it finds something useful. It usually won't.

But depending on the rest of your workflow, you might get advanced
warning of such interactions for free-ish. For example, I merge all of
my personal topics every day to the "jch" branch to build the version of
Git that I run day-to-day. So I learn about those interactions early
when my build fails, or my personal copy breaks. ;) But that's not
something I'd expect most people to do.

If you do want to look ahead, I think "next" or "jch" is often a more
useful target. A topic on the seen branch just means it was seen by the
maintainer, and might not even pass all of the tests. Whereas "next" is
fairly stable, and "jch" is (I believe) what Junio runs day to day (so a
subset of "seen" that seems pretty stable).

-Peff

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

Jeff King <peff@peff.net> writes:

> On Mon, Sep 28, 2026 at 04:41:54PM -0400, Julia Evans wrote:
>
>> > I think that is giving us a good signal, though. The guide should be
>> > mentioned in command-list.txt, so that it is linked from git(1).
>> 
>> Thanks, will fix this (and will move the conflict-marker-size change).
>> 
>> Should I be trying to apply my patches to `seen` before submitting them?
>
> In general, no, you don't have to. In this case it turned up useful
> ...
> If you do want to look ahead, I think "next" or "jch" is often a more
> useful target.

As Julia is working mostly on documentation modernization, what you
and I view as an advantage may not be as relevant to her as it is to
those who work with code.

Regardless of which "more advanced" branch you pick to cross-check
with other topics in flight, I do not think you want to apply your
patches _on_ that branch.  Rather, apply your patches on a stable
base (e.g., a release tag, or the tip of then-current 'master'), and
make a trial merge of your topic branch into the "more advanced"
target branch.

Even without building, you may find merge conflicts, through which
you will learn what other contributors are working on in the same
area.  You may run git log --merge --left-right -p right there while
you have conflicts, and may even learn that a helper function or two
your topic would benefit from have already been written in their
topics.  Even when there is no textual conflict, 'make' (just
building alone) may reveal that an API function your topic depends
on has been updated by another topic in flight, and the result does
not even build as a consequence.  Again, you learn about the topics
by others that may be very relevant to you.

If you are working in a fairly isolated area, none of the above may
happen, of course.

> A topic on the seen branch just means it was seen by the
> maintainer, and might not even pass all of the tests. Whereas "next" is
> fairly stable, and "jch" is (I believe) what Junio runs day to day (so a
> subset of "seen" that seems pretty stable).

These days my personal rule is to make sure that the topics must be
in 'jch' before it is marked with "Will merge to 'next'".

[gitgitgadget]

Patrick Steinhardt wrote on the Git mailing list (how to reply to this email):

On Thu, Sep 24, 2026 at 02:44:16PM +0000, Julia Evans via GitGitGadget wrote:
> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
> new file mode 100644
> index 0000000000..612b683e40
> --- /dev/null
> +++ b/Documentation/gitmergeconflicts.adoc
> @@ -0,0 +1,294 @@
> +gitmergeconflicts(7)
> +====================
> +
> +NAME
> +----
> +gitmergeconflicts - Guide to handling merge conflicts
> +
> +
> +SYNOPSIS
> +--------
> +Guide to handling merge conflicts
> +
> +
> +DESCRIPTION
> +-----------
> +
> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
> +cherry-pick`, `git pull`, or `git revert`. All of those commands use

Should all of these be using linkgit:, like for example in
linkgit:git-merge[1]?

> +the same merge algorithm, and the process for resolving a merge conflict
> +is always very similar.

There's also git-am(1), but only when adding the "--3way" flag. So maybe
it's best to ignore that command indeed.

> +The most common ways to handle a merge conflict are:
> +
> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
> +  below for details)
> +* Or 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.

I wonder whether the explanation should be expanded a bit to briefly
explain how Git performs a 3-way merge in the first place. I feel like
it's quite important to understand what the three different sides of the
merge are to make sense of it.

But I may be too far detached from the "normal" user, so this may only
cause more confusion for our users.

> +[[markers]]
> +MERGE CONFLICT MARKERS
> +----------------------
> +
> +Merge conflicts happen when both of the sides being merged edit the same
> +area of a file. When this happens, Git will update the conflicted file

I wonder whether we want to use "hunk" instead of "area". It's jargon
again, but I have never heard anybody speak about an "area" before
myself.

> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
> +For example, here's a merge conflict where both sides edited a list of
> +fruits in different ways:
> +
> +----
> +FRUITS = [
> +    "apple",
> +<<<<<<< HEAD
> +    "cherry",
> +=======
> +    "banana",
> +>>>>>>> add-fruit

A bit of a tangent, but sometimes I wonder whether we should make the
respective commits a bit easier to access. For example, we could put the
equivalent of `git rev-parse --reference <commit>` here for each of the
sides.

> +    "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.
> +
> +
> +[[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.
> ++
> +Note: During a `git merge`, `git commit` and `git merge --continue` do
> +the the same thing.

s/the the/the/

Maybe we should also say "During a conflicted `git merge`.", but maybe
that's redundant.

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

I tend to forget that by default, we only render ours/theirs in the
conflict. I always feel like that makes it way harder to resolve
conflicts as you don't have the context of what the code looked like
originally. So I have diff3 configured locally for ages.

> +----
> +FRUITS = [
> +    "apple",
> +    "banana",
> +    "cherry",
> +    "mango",
> +    "orange",
> +]
> +----
> +
> +
> +[[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.

There's also `git merge-tool --tool-help` to list all available drivers.

[snip]
> +[[diff3]]
> +DIFF3 AND ZDIFF3
> +----------------
> +
> +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` or `zdiff3`.
> +This extra context can make it much easier to understand what's
> +happening in a merge conflict.

Indeed.

[snip]
> +[[ours]]
> +"OURS" AND "THEIRS"
> +-------------------
> +
> +Git refers to the first part of a merge conflict (between `<<<<<<<`
> +and `=======`) as "ours" and the second part (between `=======` and
> +`>>>>>>>`) as "theirs".
> +
> +Normally, "ours" is the commit that was checked out before you started
> +the merge, and "theirs" is the other commit.
> +
> +But when the merge conflict was caused by a `git rebase`, it's the
> +opposite: "theirs" is the commit that was checked out before you started
> +the merge. This is because under the hood, `git rebase main` checks out
> +the `main` commit first before doing the merge operation.

Hmm. This part is a bit confusing to me. "ours" is always the commit
that's currently checked out, and "theirs" is always the one that is
getting merged into the checked-out commit.

How about a variant of the following instead?

  In a conflict, the side between `<<<<<<<` and `=======` is "ours"
  and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is
  always the side that `HEAD` points to while the merge happens; "theirs"
  is the commit being merged into it.

  For `git merge <other>`, `HEAD` is your current branch, so "ours" is
  your branch and "theirs" is `<other>`.

  For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and
  your commits are then replayed on top one at a time. So "ours" is the
  already-rebased history starting at `<upstream>`, and "theirs" is the
  commit from your original branch that is currently being replayed.

> +These terms in Git all mean the same thing when dealing with a merge
> +conflict:
> +
> +* "common ancestor", "base", and "stage 1"
> +* "ours", "us", "stage 2", and `HEAD`
> +* "theirs", "them", and "stage 3"

I wouldn't say that "stage N" is equivalent to the respective other
terms. These stages rather refer to the different versions of a specific
file as recorded in the index, they do not indicate a specific commit.
In contrast to that, all the other terms may also indicate a specific
version of a file, but may also refer to the commits.

Patrick

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

>> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
>> +cherry-pick`, `git pull`, or `git revert`. All of those commands use
>
> Should all of these be using linkgit:, like for example in
> linkgit:git-merge[1]?

Makes sense to me, will change.

>> +The most common ways to handle a merge conflict are:
>> +
>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
>> +  below for details)
>> +* Or 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.
>
> I wonder whether the explanation should be expanded a bit to briefly
> explain how Git performs a 3-way merge in the first place. I feel like
> it's quite important to understand what the three different sides of the
> merge are to make sense of it.
>
> But I may be too far detached from the "normal" user, so this may only
> cause more confusion for our users.

I think it would cause more confusion. I did some experiments in explaining
merge conflicts using the concept of 3-way merge a couple of years
ago and it didn't go well.

My experience was that what users they found the most useful was
learning about the tools Git offers (like `git diff --check` and `diff3`),
so that's why this document focuses on tools and formatting much
more than concepts.

I think it would be cool to find a way to explain how 3-way merge works at in
this document in some later iteration though, maybe at the end. Definitely some
folks would find it interesting. I didn't understand 3-way merge myself until a
couple of years ago and it was fun for me to learn, but it didn't really help me
use Git effectively.

(this is quickly becoming a bit of a novel, but it's often very counterintuitive
how some facts that seem "fundamental" about how Git works actually turn
out to not be very important to understand in practice to use it effectively.
It's something I find tough to talk about on this mailing list because it's something
I've only been able to learn empirically)

>> +[[markers]]
>> +MERGE CONFLICT MARKERS
>> +----------------------
>> +
>> +Merge conflicts happen when both of the sides being merged edit the same
>> +area of a file. When this happens, Git will update the conflicted file
>
> I wonder whether we want to use "hunk" instead of "area". It's jargon
> again, but I have never heard anybody speak about an "area" before
> myself.

Ah thanks, I think I took "area" from the `git-merge` man page.

I looked up how I explained this previously and I used "lines of code",
which I think communicates the same meaning without the jargon.
I'll try that instead.

>> +Note: During a `git merge`, `git commit` and `git merge --continue` do
>> +the the same thing.
>
> s/the the/the/

Will fix. 

>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
>> +For example, here's a merge conflict where both sides edited a list of
>> +fruits in different ways:
>> +
>> +----
>> +FRUITS = [
>> +    "apple",
>> +<<<<<<< HEAD
>> +    "cherry",
>> +=======
>> +    "banana",
>> +>>>>>>> add-fruit
> Hide quoted text
>
> A bit of a tangent, but sometimes I wonder whether we should make the
> respective commits a bit easier to access. For example, we could put the
> equivalent of `git rev-parse --reference <commit>` here for each of the
> sides.

Personally I'm not sure if the commit ID would do much for me, but I feel
like it would help me if it were possible to include the commit message. 

> I tend to forget that by default, we only render ours/theirs in the
> conflict. I always feel like that makes it way harder to resolve
> conflicts as you don't have the context of what the code looked like
> originally. So I have diff3 configured locally for ages.

Every time I show people diff3 someone tells me how happy they
are to learn it :)

>> +* 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.
>
> There's also `git merge-tool --tool-help` to list all available drivers.

Oh, cool! It's fun that it autodetects which ones you have installed
on your system. I'll suggest that.

>
> [snip]
>> +[[ours]]
>> +"OURS" AND "THEIRS"
>> +-------------------
>> +
>> +Git refers to the first part of a merge conflict (between `<<<<<<<`
>> +and `=======`) as "ours" and the second part (between `=======` and
>> +`>>>>>>>`) as "theirs".
>> +
>> +Normally, "ours" is the commit that was checked out before you started
>> +the merge, and "theirs" is the other commit.
>> +
>> +But when the merge conflict was caused by a `git rebase`, it's the
>> +opposite: "theirs" is the commit that was checked out before you started
>> +the merge. This is because under the hood, `git rebase main` checks out
>> +the `main` commit first before doing the merge operation.
>
> Hmm. This part is a bit confusing to me. "ours" is always the commit
> that's currently checked out, and "theirs" is always the one that is
> getting merged into the checked-out commit.
>
> How about a variant of the following instead?
>
>   In a conflict, the side between `<<<<<<<` and `=======` is "ours"
>   and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is
>   always the side that `HEAD` points to while the merge happens; "theirs"
>   is the commit being merged into it.
>
>   For `git merge <other>`, `HEAD` is your current branch, so "ours" is
>   your branch and "theirs" is `<other>`.
>
>   For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and
>   your commits are then replayed on top one at a time. So "ours" is the
>   already-rebased history starting at `<upstream>`, and "theirs" is the
>   commit from your original branch that is currently being replayed.

Thanks, your suggestion gives me some other ways to think about this.

I think I'll try to write something shorter that is unambiguous, instead of trying
to use more words to make it feel more intuitive. I don't think I actually know
anyone who feels it's easy to understand the way merge conflicts are
presented, and more explanation may not help.

It might be more useful here to encourage (again) folks to use one of the many
amazing tools available (in the "tools" section) to get more context.

>> +These terms in Git all mean the same thing when dealing with a merge
>> +conflict:
>> +
>> +* "common ancestor", "base", and "stage 1"
>> +* "ours", "us", "stage 2", and `HEAD`
>> +* "theirs", "them", and "stage 3"
>
> I wouldn't say that "stage N" is equivalent to the respective other
> terms. These stages rather refer to the different versions of a specific
> file as recorded in the index, they do not indicate a specific commit.
> In contrast to that, all the other terms may also indicate a specific
> version of a file, but may also refer to the commits.

Thanks, will try to figure out how to make it more accurate.
We could also refer to gitdatamodel if folks want to learn what the
term "stage" means too.

Thanks for the review!
- Julia

[gitgitgadget]

Junio C Hamano wrote on the Git mailing list (how to reply to this email):

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

>>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
>>> +For example, here's a merge conflict where both sides edited a list of
>>> +fruits in different ways:
>>> +
>>> +----
>>> +FRUITS = [
>>> +    "apple",
>>> +<<<<<<< HEAD
>>> +    "cherry",
>>> +=======
>>> +    "banana",
>>> +>>>>>>> add-fruit
>> Hide quoted text
>>
>> A bit of a tangent, but sometimes I wonder whether we should make the
>> respective commits a bit easier to access. For example, we could put the
>> equivalent of `git rev-parse --reference <commit>` here for each of the
>> sides.
>
> Personally I'm not sure if the commit ID would do much for me, but I feel
> like it would help me if it were possible to include the commit message. 

It would also help the resolution, not just committing after you are
done.  It may not matter while picking between cherry and banana to
show your personal preference on fruits, but in a more involved
conflicted merge, it may help to be able to view "git show $commit",
"git diff ...$commit", and "git diff $commit..." where $commit is
the "add-fruit" side of the merge to understand what they wanted to
do, and what we have done while they weren't looking.

>> I tend to forget that by default, we only render ours/theirs in the
>> conflict. I always feel like that makes it way harder to resolve
>> conflicts as you don't have the context of what the code looked like
>> originally. So I have diff3 configured locally for ages.
>
> Every time I show people diff3 someone tells me how happy they
> are to learn it :)

Yes, we should encourage "merge.conflictstyle=diff3" (I feel about
this strongly enough to think it should become the default).
Knowing what the original was before one side wanted to say "cherry"
while the other side wanted to say "banana" sometimes helps a great
deal to decide what to do with the conflict.

[gitgitgadget]

Patrick Steinhardt wrote on the Git mailing list (how to reply to this email):

On Wed, Sep 30, 2026 at 01:37:16PM -0700, Junio C Hamano wrote:
> "Julia Evans" <julia@jvns.ca> writes:
> 
> >>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
> >>> +For example, here's a merge conflict where both sides edited a list of
> >>> +fruits in different ways:
> >>> +
> >>> +----
> >>> +FRUITS = [
> >>> +    "apple",
> >>> +<<<<<<< HEAD
> >>> +    "cherry",
> >>> +=======
> >>> +    "banana",
> >>> +>>>>>>> add-fruit
> >> Hide quoted text
> >>
> >> A bit of a tangent, but sometimes I wonder whether we should make the
> >> respective commits a bit easier to access. For example, we could put the
> >> equivalent of `git rev-parse --reference <commit>` here for each of the
> >> sides.
> >
> > Personally I'm not sure if the commit ID would do much for me, but I feel
> > like it would help me if it were possible to include the commit message. 
> 
> It would also help the resolution, not just committing after you are
> done.  It may not matter while picking between cherry and banana to
> show your personal preference on fruits, but in a more involved
> conflicted merge, it may help to be able to view "git show $commit",
> "git diff ...$commit", and "git diff $commit..." where $commit is
> the "add-fruit" side of the merge to understand what they wanted to
> do, and what we have done while they weren't looking.

Yup. Doesn't mean we cannot _also_ include the names that we have above.
So in the above example it could be for example:

+FRUITS = [
+    "apple",
+<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01)
+    "cherry",
+=======
+    "banana",
+>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03)

That format would have a bunch of advantages:

  - We don't have to teach users about special refs like MERGE_HEAD to
    let them figure out how to access each of the commits.

  - It gives a bit more context about what each specific side does, at
    least if you have good commit messages.

  - It also gives a sense of timing because we include dates, and that
    may help in some situations to figure out what's what.

I'll create an issue on the GitLab side and ask someone in the team to
maybe give this a try.

> >> I tend to forget that by default, we only render ours/theirs in the
> >> conflict. I always feel like that makes it way harder to resolve
> >> conflicts as you don't have the context of what the code looked like
> >> originally. So I have diff3 configured locally for ages.
> >
> > Every time I show people diff3 someone tells me how happy they
> > are to learn it :)
> 
> Yes, we should encourage "merge.conflictstyle=diff3" (I feel about
> this strongly enough to think it should become the default).
> Knowing what the original was before one side wanted to say "cherry"
> while the other side wanted to say "banana" sometimes helps a great
> deal to decide what to do with the conflict.

I very much agree that it should be the default.

Patrick

[gitgitgadget]

"Julia Evans" wrote on the Git mailing list (how to reply to this email):

> +FRUITS = [
> +    "apple",
> +<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01)
> +    "cherry",
> +=======
> +    "banana",
> +>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03)
>
> That format would have a bunch of advantages:
>
>   - We don't have to teach users about special refs like MERGE_HEAD to
>     let them figure out how to access each of the commits.
>
>   - It gives a bit more context about what each specific side does, at
>     least if you have good commit messages.
>
>   - It also gives a sense of timing because we include dates, and that
>     may help in some situations to figure out what's what.

This is so cool, I love the idea of including the dates and the commit
messages!!! I think this would be very helpful for the reasons you say. 

Though re "We don't have to teach users about special refs
like MERGE_HEAD": I think that users today could run`git show HEAD`
or `git show add-fruit` to see the commits on each side? I've never
used MERGE_HEAD though so maybe I'm misunderstanding what
it does. I think adding the commit ID makes it clearer too.

I just ran downstairs to show my partner this example at 8am
because I was so excited about it :) (he liked it too)

[gitgitgadget]

Patrick Steinhardt wrote on the Git mailing list (how to reply to this email):

On Thu, Sep 24, 2026 at 02:44:17PM +0000, Julia Evans via GitGitGadget wrote:
> From: Julia Evans <julia@jvns.ca>
> 
> All of the info about merge conflicts has been moved to the new guide

Pedantic nit: missing punctuation.

Other than that I agree with Ben, one part that we lose here is some
context on what a merge conflict even is.

Patrick