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

Changed in v2:

• Explain what a merge conflict is (thanks to Junio & Ben)
• rewrite the "ours" vs "theirs" section (thanks to Patrick for the comments)
• add git log --merge (thanks to Ben)
• Leave most of the content of git cherry-pick as-is, to make this patch set smaller (thanks to Junio)
• remove the SYNOPSIS since hopefully that won't be required anymore by the time this is merged
• Fix a typo in git revert (s/reverted conflict/reverted commit/)
• 's/the the/the/' (thanks to Patrick)
• s/[doc] Thing/doc: thing/ in commit messages (thanks to Tuomas)'
• squash the commit fixing the linter error (thanks to Junio)
• list reviewers in Reviewed-by

Changed in v3:

Thanks to all the comments from Junio.

• Add signoff from Marie
• In "For example, here's a merge conflict where both sides edited a list of", add a little more detail about how to interpret the merge conflict
• When we introduce a merge mention "semantic merge conflicts"
• Say "... and any other command that does a merge" when listing commands that can cause merge conflicts.
• Reviewed-by is not the right thing, use Helped-by
• Adjust phrasing in git revert and git cherry-pick man pages
• Reference the "ours" section in "git show :2:filename shows the "ours""
• "there's one file left with conflicts in it: fruits.py" isn't precise enough, instead say "the conflicts in fruits.py haven't been marked as resolved"
• Delete the explanation of zdiff3 and add a brief warning instead. Don't be too prescriptive, we should tell people what the issue is (ambiguity) instead of trying to impose our opinion.
• Explain ||||||| when we add diff3
• Fix example in "EXAMPLE OF RESOLVING A MERGE CONFLICT" to make it consistent with the other examples
• Replace "configuration option" with "configuration variable"
• Mention --skip instead of saying "the most common ways", which is ambiguous
• Add a pointer to the extended AUTO_MERGE sentence

Changed in v4:

changes to the content:

• use Junio's much better example for diff3
• clarify in the commit message why we're not mentioning git apply: to avoid dealing with patches (thanks to Junio)
• adjust the wording around "multi-step operation like a rebase" (thanks to Junio)
• Say "see git-config for more" in the description of zdiff3. Like Patrick said the explanation of zdiff3 is not really satisfiying, but I don't know how to write a satisfying explanation, and it's better to have a short and obviously unsatisfying explanation than a long unsatisfying one. Added a note in the commit message that perhaps this should be improved in the future. (from Patrick's comment)

changes cleaning things up:

• add periods at the ends of various sentences in an attempt to be more consistent (thanks to Junio & Patrick)
• Adjust the formatting around the [NOTE] to make the CI whitespace check pass
• Replace a couple of instances of "code" with "lines" (thanks to Junio)
• Fix Ben's email address (thanks to Ben)
• Remove the double signoff (thanks to Ben).
• Make the cherry-pick commit message more accurate (thanks to Patrick)

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

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

[gitgitgadget]

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

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

[gitgitgadget]

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

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

;-).

[gitgitgadget]

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

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

[gitgitgadget]

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

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

[gitgitgadget]

There are issues in commit 757ff66:
fixup! doc: add new gitmergeconflicts man page

• Commit checks stopped - the message is too short
• Rebase needed to squash commit
• Commit not signed off

[gitgitgadget]

There are issues in commit 538910f:
fixup! doc: add new gitmergeconflicts man page

• Commit checks stopped - the message is too short
• Rebase needed to squash commit
• Commit not signed off

[gitgitgadget]

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

A new user manual page on how to resolve merge conflicts has been
introduced, and other commands that could encounter conflicts have
been updated to link to it.

Expecting a reroll.
cf. <695c53d0-6e14-4f4c-a3be-33a8e331f563@app.fastmail.com>
source: <pull.2237.v3.git.1791816795.gitgitgadget@gmail.com>

[gitgitgadget]

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

A new user manual page on how to resolve merge conflicts has been
introduced, and other commands that could encounter conflicts have
been updated to link to it.

Expecting a reroll.
cf. <695c53d0-6e14-4f4c-a3be-33a8e331f563@app.fastmail.com>
source: <pull.2237.v3.git.1791816795.gitgitgadget@gmail.com>

[gitgitgadget]

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

A new user manual page on how to resolve merge conflicts has been
introduced, and other commands that could encounter conflicts have
been updated to link to it.

Expecting a reroll.
cf. <695c53d0-6e14-4f4c-a3be-33a8e331f563@app.fastmail.com>
source: <pull.2237.v3.git.1791816795.gitgitgadget@gmail.com>

[jvns]

/submit

[gitgitgadget]

Submitted as pull.2237.v4.git.1792764293.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

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

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

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

[gitgitgadget]

This patch series is no longer integrated into seen.

[gitgitgadget]

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

> Le 23 oct. 2026 à 10:04, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :
> 
> 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.
> 
> Changed in v2:
> 
> * Explain what a merge conflict is (thanks to Junio & Ben)
> * rewrite the "ours" vs "theirs" section (thanks to Patrick for the
>   comments)
> * add git log --merge (thanks to Ben)
> * Leave most of the content of git cherry-pick as-is, to make this patch
>   set smaller (thanks to Junio)
> * remove the SYNOPSIS since hopefully that won't be required anymore by the
>   time this is merged
> * Fix a typo in git revert (s/reverted conflict/reverted commit/)
> * 's/the the/the/' (thanks to Patrick)
> * s/[doc] Thing/doc: thing/ in commit messages (thanks to Tuomas)'
> * squash the commit fixing the linter error (thanks to Junio)
> * list reviewers in Reviewed-by
> 
> Changed in v3:
> 
> Thanks to all the comments from Junio.
> 
> * Add signoff from Marie
> * In "For example, here's a merge conflict where both sides edited a list
>   of", add a little more detail about how to interpret the merge conflict
> * When we introduce a merge mention "semantic merge conflicts"
> * Say "... and any other command that does a merge" when listing commands
>   that can cause merge conflicts.
> * Reviewed-by is not the right thing, use Helped-by
> * Adjust phrasing in git revert and git cherry-pick man pages
> * Reference the "ours" section in "git show :2:filename shows the "ours""
> * "there's one file left with conflicts in it: fruits.py" isn't precise
>   enough, instead say "the conflicts in fruits.py haven't been marked as
>   resolved"
> * Delete the explanation of zdiff3 and add a brief warning instead. Don't
>   be too prescriptive, we should tell people what the issue is (ambiguity)
>   instead of trying to impose our opinion.
> * Explain ||||||| when we add diff3
> * Fix example in "EXAMPLE OF RESOLVING A MERGE CONFLICT" to make it
>   consistent with the other examples
> * Replace "configuration option" with "configuration variable"
> * Mention --skip instead of saying "the most common ways", which is
>   ambiguous
> * Add a pointer to the extended AUTO_MERGE sentence
> 
> Changed in v4:
> 
> changes to the content:
> 
> * use Junio's much better example for diff3
> * clarify in the commit message why we're not mentioning git apply: to
>   avoid dealing with patches (thanks to Junio)
> * adjust the wording around "multi-step operation like a rebase" (thanks to
>   Junio)
> * Say "see git-config for more" in the description of zdiff3. Like Patrick
>   said the explanation of zdiff3 is not really satisfiying, but I don't
>   know how to write a satisfying explanation, and it's better to have a
>   short and obviously unsatisfying explanation than a long unsatisfying
>   one. Added a note in the commit message that perhaps this should be
>   improved in the future. (from Patrick's comment)
> 
> changes cleaning things up:
> 
> * add periods at the ends of various sentences in an attempt to be more
>   consistent (thanks to Junio & Patrick)
> * Adjust the formatting around the [NOTE] to make the CI whitespace check
>   pass
> * Replace a couple of instances of "code" with "lines" (thanks to Junio)
> * Fix Ben's email address (thanks to Ben)
> * Remove the double signoff (thanks to Ben).
> * Make the cherry-pick commit message more accurate (thanks to Patrick)
> 
> 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.

I’m happy with this version based on the range-diff, and
I suspect we are reaching the point of diminishing returns. 

[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/gitmergeconflicts.adoc (new)
>       +    "cherry",
>       +    "mango",
>       +||||||| 1c22e48
>      ++	"banana",
>      ++	"cherry",
>       +    "mangoooo",
>       +=======

Is it intended to use different indentation style for the entries to
be removed from the list, or is it a simple mistake?

>       +    "banana",
>      @@ Documentation/gitmergeconflicts.adoc (new)
>       +]
>       +----
>       +
>      ++With this view, you can see that both sides fixed a spelling
>      ++mistake in "mango", and each removed one fruit to the list.

"removed one fruit *from* the list", no?

I'll block time to read the whole thing over later today.  Thanks.

[gitgitgadget]

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

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

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

$ make check-docs
GIT_VERSION=2.56.0.rc2.6.gf97f562a2c
make -C Documentation lint-docs
make[1]: Entering directory '/home/gitster/w/git/Documentation'
    LINT MAN SEC gitmergeconflicts.adoc
gitmergeconflicts.adoc:339: has no required 'SYNOPSIS' section!

[gitgitgadget]

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

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

> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> 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.
>
> $ make check-docs
> GIT_VERSION=2.56.0.rc2.6.gf97f562a2c
> make -C Documentation lint-docs
> make[1]: Entering directory '/home/gitster/w/git/Documentation'
>     LINT MAN SEC gitmergeconflicts.adoc
> gitmergeconflicts.adoc:339: has no required 'SYNOPSIS' section!

Ah, nevermind. Merge to 'seen' is (and has been) taking care of this
already.

[gitgitgadget]

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

[gitgitgadget]

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

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

> Things to potentially improve in future docs revisions:
>
> - The explanation of zdiff3 is unsatisfying. It would be good if we
>   could have a clear example of a case where zdiff3 is helpful and a
>   case where it's harmful, and if we could give a better sense for
>   the reasons why users are actually choosing zdiff3 over diff3
>   (or the reverse) in real life.

Is this a stale comment?  I think you reduced this to just a side
note that says `shoter but ambiguous`, which is probably good
enough.

> +[[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.
> +
> +----
> +FRUITS = [
> +    "apple",
> +<<<<<<< HEAD
> +    "cherry",
> +    "mango",
> +||||||| 1c22e48
> +	"banana",
> +	"cherry",

These two should be indented with spaces the same way as all the
other lines in this list.

> +    "mangoooo",
> +=======
> +    "banana",
> +    "mango",
> +>>>>>>> add-fruit
> +    "orange",
> +]
> +----
> +
> +With this view, you can see that both sides fixed a spelling
> +mistake in "mango", and each removed one fruit to the list.

", and each removed one from the list", I think.

> +This makes it more clear how to resolve the merge conflict: since one
> +side removed `banana` and one side removed `cherry`, it would probably
> +make sense to remove both from the list, like this:

The reason why removal becomes the correct resolution is not just
one side removed, but the fact that the other side did not touch
what was removed by one side.  The "indifference by the other" is
what makes one's removal the preferred action by the semantics of
3-way merge.

So, let's rewrite the reason a bit more tightly.

    since one side removed `banana` while the other side did not
    touch, and the same happend to `cherry`, it makes sense to
    remove both from the list ...

or somethig like that.

Other than that, I did not see anything questionable in the 6
patches.

[gitgitgadget]

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

On Fri, Oct 23, 2026, at 3:14 PM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> Things to potentially improve in future docs revisions:
>>
>> - The explanation of zdiff3 is unsatisfying. It would be good if we
>>   could have a clear example of a case where zdiff3 is helpful and a
>>   case where it's harmful, and if we could give a better sense for
>>   the reasons why users are actually choosing zdiff3 over diff3
>>   (or the reverse) in real life.
>
> Is this a stale comment?  I think you reduced this to just a side
> note that says `shoter but ambiguous`, which is probably good
> enough.

It's not, but I'll delete it anyway because I don't think it's adding much.

>> +[[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.
>> +
>> +----
>> +FRUITS = [
>> +    "apple",
>> +<<<<<<< HEAD
>> +    "cherry",
>> +    "mango",
>> +||||||| 1c22e48
>> +	"banana",
>> +	"cherry",
>
> These two should be indented with spaces the same way as all the
> other lines in this list.

Will fix, thanks.

>> +    "mangoooo",
>> +=======
>> +    "banana",
>> +    "mango",
>> +>>>>>>> add-fruit
>> +    "orange",
>> +]
>> +----
>> +
>> +With this view, you can see that both sides fixed a spelling
>> +mistake in "mango", and each removed one fruit to the list.
>
> ", and each removed one from the list", I think.

Thanks, will fix.

>> +This makes it more clear how to resolve the merge conflict: since one
>> +side removed `banana` and one side removed `cherry`, it would probably
>> +make sense to remove both from the list, like this:
>
> The reason why removal becomes the correct resolution is not just
> one side removed, but the fact that the other side did not touch
> what was removed by one side.  The "indifference by the other" is
> what makes one's removal the preferred action by the semantics of
> 3-way merge.
>
> So, let's rewrite the reason a bit more tightly.
>
>     since one side removed `banana` while the other side did not
>     touch, and the same happend to `cherry`, it makes sense to
>     remove both from the list ...

I tried to edit this (like below) but only ended up removing "probably".
But "probably" was there for a reason, since this is a made up example
and in the real world you would really need to apply some judgement
to know what the right thing to do is. I left it as is.

-side removed `banana` and one side removed `cherry`, it would probably
-make sense to remove both from the list, like this:
+side removed `banana` and one side removed `cherry`, it makes sense
+to remove both from the list, like this:

> or somethig like that.
>
> Other than that, I did not see anything questionable in the 6
> patches.

[gitgitgadget]

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

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

>> So, let's rewrite the reason a bit more tightly.
>>
>>     since one side removed `banana` while the other side did not
>>     touch, and the same happend to `cherry`, it makes sense to
>>     remove both from the list ...
>
> I tried to edit this (like below) but only ended up removing "probably".
> But "probably" was there for a reason, since this is a made up example
> and in the real world you would really need to apply some judgement
> to know what the right thing to do is. I left it as is.
>
> -side removed `banana` and one side removed `cherry`, it would probably
> -make sense to remove both from the list, like this:
> +side removed `banana` and one side removed `cherry`, it makes sense
> +to remove both from the list, like this:

Are we talking past each other?  I did not mean "probably" was not
tight enough, and probably is probably a good thing to have there.

The value I wanted to bring on the table was to point out that the
changes are not just "one side did something", but "one side did
something where the other side had no opinion on (hence it didn't do
anything)".  It is the basis of how 3-way merge works and helps to
resolve the example for removal of both.

[gitgitgadget]

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

On Mon, Oct 26, 2026, at 10:37 AM, Junio C Hamano wrote:
> "Julia Evans" <julia@jvns.ca> writes:
>
>>> So, let's rewrite the reason a bit more tightly.
>>>
>>>     since one side removed `banana` while the other side did not
>>>     touch, and the same happend to `cherry`, it makes sense to
>>>     remove both from the list ...
>>
>> I tried to edit this (like below) but only ended up removing "probably".
>> But "probably" was there for a reason, since this is a made up example
>> and in the real world you would really need to apply some judgement
>> to know what the right thing to do is. I left it as is.
>>
>> -side removed `banana` and one side removed `cherry`, it would probably
>> -make sense to remove both from the list, like this:
>> +side removed `banana` and one side removed `cherry`, it makes sense
>> +to remove both from the list, like this:
>
> Are we talking past each other?  I did not mean "probably" was not
> tight enough, and probably is probably a good thing to have there.
>
> The value I wanted to bring on the table was to point out that the
> changes are not just "one side did something", but "one side did
> something where the other side had no opinion on (hence it didn't do
> anything)".  It is the basis of how 3-way merge works and helps to
> resolve the example for removal of both.

Oh, I see.  This is such a simple example that IMO trying to explain
in more detail exactly "why" the resolution is correct risks confusing
people. My goal with saying "one side removed 'banana'" is just
to give an example of how to read what the merge conflict above is
saying, since the syntax might be new to people.

[gitgitgadget]

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

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

>> The value I wanted to bring on the table was to point out that the
>> changes are not just "one side did something", but "one side did
>> something where the other side had no opinion on (hence it didn't do
>> anything)".  It is the basis of how 3-way merge works and helps to
>> resolve the example for removal of both.
>
> Oh, I see.  This is such a simple example that IMO trying to explain
> in more detail exactly "why" the resolution is correct risks confusing
> people. My goal with saying "one side removed 'banana'" is just
> to give an example of how to read what the merge conflict above is
> saying, since the syntax might be new to people.

OK.  Other than that, I do not think anybody saw an issue in this
iteration, and I suspect that we are reaching the point of diminishing
returns.  Let me mark the topic as ready for 'next'.

THanks.

[gitgitgadget]

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

A new user manual page on how to resolve merge conflicts has been
introduced, and other commands that could encounter conflicts have
been updated to link to it.

Waiting for response.
cf. <254688CB-AD21-4283-AE19-F1061C90C6B3@gmail.com>
cf. <xmqqtsmc44c1.fsf@gitster.g>
source: <pull.2237.v4.git.1792764293.gitgitgadget@gmail.com>

[jvns]

/submit

[gitgitgadget]

Submitted as pull.2237.v5.git.1793018405.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

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

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

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