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

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

[gitgitgadget]

This patch series is no longer integrated into seen.