[doc] Add new page on merge conflicts #2237
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -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 | ||
|
There was a problem hiding this comment. 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
> --- |
||
| working tree to be clean (no modifications from the HEAD commit). | ||
|
|
||
| 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. | ||
|
|
||
| OPTIONS | ||
| ------- | ||
|
|
@@ -259,6 +243,7 @@ $ git cherry-pick -Xpatience topic^ <4> | |
| SEE ALSO | ||
| -------- | ||
| linkgit:git-revert[1] | ||
| linkgit:gitmergeconflicts[7] | ||
|
|
||
| GIT | ||
| --- | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -49,7 +49,8 @@ a log message from the user describing the changes. Before the operation, | |
| A merge stops if there's a conflict that cannot be resolved | ||
|
There was a problem hiding this comment. "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 KnobleThere was a problem hiding this comment. "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.There was a problem hiding this comment. 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.There was a problem hiding this comment. 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 ;)There was a problem hiding this comment. 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. There was a problem hiding this comment. 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. |
||
| automatically or if `--no-commit` was provided when initiating the | ||
| merge. At that point you can run `git merge --abort` or `git merge | ||
| --continue`. See linkgit:gitmergeconflicts[7] | ||
| (or `git help mergeconflicts`) for a guide to handling merge conflicts. | ||
|
|
||
| `git merge --abort` will abort the merge process and try to reconstruct | ||
| the pre-merge state. However, if there were uncommitted changes when the | ||
|
|
@@ -231,127 +232,6 @@ git merge v1.2.3^0 | |
| git merge --ff-only v1.2.3 | ||
| ---- | ||
|
|
||
| EXAMPLES | ||
| -------- | ||
|
|
||
|
|
@@ -406,6 +286,7 @@ linkgit:git-reset[1], | |
| linkgit:git-diff[1], linkgit:git-ls-files[1], | ||
| linkgit:git-add[1], linkgit:git-rm[1], | ||
| linkgit:git-mergetool[1] | ||
| linkgit:gitmergeconflicts[7] | ||
|
|
||
| GIT | ||
| --- | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Junio C Hamano wrote on the Git mailing list (how to reply to this email):
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Junio C Hamano wrote on the Git mailing list (how to reply to this email):