[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
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc | |
| MAN7_TXT += giteveryday.adoc | ||
|
There was a problem hiding this comment. Patrick Steinhardt wrote on the Git mailing list (how to reply to this email): On Thu, Sep 24, 2026 at 02:44:16PM +0000, Julia Evans via GitGitGadget wrote:
> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
> new file mode 100644
> index 0000000000..612b683e40
> --- /dev/null
> +++ b/Documentation/gitmergeconflicts.adoc
> @@ -0,0 +1,294 @@
> +gitmergeconflicts(7)
> +====================
> +
> +NAME
> +----
> +gitmergeconflicts - Guide to handling merge conflicts
> +
> +
> +SYNOPSIS
> +--------
> +Guide to handling merge conflicts
> +
> +
> +DESCRIPTION
> +-----------
> +
> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
> +cherry-pick`, `git pull`, or `git revert`. All of those commands use
Should all of these be using linkgit:, like for example in
linkgit:git-merge[1]?
> +the same merge algorithm, and the process for resolving a merge conflict
> +is always very similar.
There's also git-am(1), but only when adding the "--3way" flag. So maybe
it's best to ignore that command indeed.
> +The most common ways to handle a merge conflict are:
> +
> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
> + below for details)
> +* Or stop the operation and return your branch to its original state
> + with the appropriate `--abort` command, for example `git merge --abort`
> + or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
> + for how to find the command to run.
I wonder whether the explanation should be expanded a bit to briefly
explain how Git performs a 3-way merge in the first place. I feel like
it's quite important to understand what the three different sides of the
merge are to make sense of it.
But I may be too far detached from the "normal" user, so this may only
cause more confusion for our users.
> +[[markers]]
> +MERGE CONFLICT MARKERS
> +----------------------
> +
> +Merge conflicts happen when both of the sides being merged edit the same
> +area of a file. When this happens, Git will update the conflicted file
I wonder whether we want to use "hunk" instead of "area". It's jargon
again, but I have never heard anybody speak about an "area" before
myself.
> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
> +For example, here's a merge conflict where both sides edited a list of
> +fruits in different ways:
> +
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry",
> +=======
> + "banana",
> +>>>>>>> add-fruit
A bit of a tangent, but sometimes I wonder whether we should make the
respective commits a bit easier to access. For example, we could put the
equivalent of `git rev-parse --reference <commit>` here for each of the
sides.
> + "mango",
> + "orange",
> +]
> +----
> +
> +The code from one side of the merge conflict is between `<<<<<<<` and
> +`=======`, and the code for the other side is between `=======` and
> +`>>>>>>>`. See <<ours,"OURS" AND "THEIRS">> below for a full explanation
> +of which side is which.
> +
> +
> +[[resolve]]
> +HOW TO RESOLVE A MERGE CONFLICT
> +-------------------------------
> +
> +The process for resolving a merge conflict is:
> +
> +1. Run `git status` to get a list of files with merge conflicts
> +2. For each one, find the conflict markers
> + (the `<<<<<<<`, `=======`, `>>>>>>>`) and edit the code to
> + fix the conflict
> +3. Run `git add FILENAME` for each file to mark the conflict as resolved
> +4. Run the appropriate `--continue` command to continue the operation
> + that was interrupted by the conflict, for example `git merge --continue`
> + or `git rebase --continue`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>>
> + below for how to find the command to run.
> ++
> +Note: During a `git merge`, `git commit` and `git merge --continue` do
> +the the same thing.
s/the the/the/
Maybe we should also say "During a conflicted `git merge`.", but maybe
that's redundant.
> +[[example]]
> +EXAMPLE OF RESOLVING A MERGE CONFLICT
> +-------------------------------------
> +
> +If you see this in your code during a merge conflict:
> +
> +----
> +FRUITS = [
> + "apple",
> +<<<<<<< HEAD
> + "cherry",
> + "mango",
> +=======
> + "banana",
> + "mango",
> +>>>>>>> add-fruit
> + "orange",
> +]
> +----
> +
> +Then you might edit that part of the code like this,
> +which includes the fruits from both sides of the conflict:
I tend to forget that by default, we only render ours/theirs in the
conflict. I always feel like that makes it way harder to resolve
conflicts as you don't have the context of what the code looked like
originally. So I have diff3 configured locally for ages.
> +----
> +FRUITS = [
> + "apple",
> + "banana",
> + "cherry",
> + "mango",
> + "orange",
> +]
> +----
> +
> +
> +[[tools]]
> +TOOLS FOR HANDLING MERGE CONFLICTS
> +----------------------------------
> +
> +Here are some ways to get extra context while handling a merge conflict:
> +
> +* There are many graphical "merge tools" for Git, which will normally
> + show you the different versions of the code side by side.
> + If you have a mergetool configured, `git mergetool` will launch it.
> + See also `merge.tool` in linkgit:git-config[1] for a list of
> + the mergetools Git supports.
There's also `git merge-tool --tool-help` to list all available drivers.
[snip]
> +[[diff3]]
> +DIFF3 AND ZDIFF3
> +----------------
> +
> +By default, Git doesn't include the original code when formatting
> +a merge conflict. To include the original code, you can set the
> +configuration option `merge.conflictstyle` to `diff3` or `zdiff3`.
> +This extra context can make it much easier to understand what's
> +happening in a merge conflict.
Indeed.
[snip]
> +[[ours]]
> +"OURS" AND "THEIRS"
> +-------------------
> +
> +Git refers to the first part of a merge conflict (between `<<<<<<<`
> +and `=======`) as "ours" and the second part (between `=======` and
> +`>>>>>>>`) as "theirs".
> +
> +Normally, "ours" is the commit that was checked out before you started
> +the merge, and "theirs" is the other commit.
> +
> +But when the merge conflict was caused by a `git rebase`, it's the
> +opposite: "theirs" is the commit that was checked out before you started
> +the merge. This is because under the hood, `git rebase main` checks out
> +the `main` commit first before doing the merge operation.
Hmm. This part is a bit confusing to me. "ours" is always the commit
that's currently checked out, and "theirs" is always the one that is
getting merged into the checked-out commit.
How about a variant of the following instead?
In a conflict, the side between `<<<<<<<` and `=======` is "ours"
and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is
always the side that `HEAD` points to while the merge happens; "theirs"
is the commit being merged into it.
For `git merge <other>`, `HEAD` is your current branch, so "ours" is
your branch and "theirs" is `<other>`.
For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and
your commits are then replayed on top one at a time. So "ours" is the
already-rebased history starting at `<upstream>`, and "theirs" is the
commit from your original branch that is currently being replayed.
> +These terms in Git all mean the same thing when dealing with a merge
> +conflict:
> +
> +* "common ancestor", "base", and "stage 1"
> +* "ours", "us", "stage 2", and `HEAD`
> +* "theirs", "them", and "stage 3"
I wouldn't say that "stage N" is equivalent to the respective other
terms. These stages rather refer to the different versions of a specific
file as recorded in the index, they do not indicate a specific commit.
In contrast to that, all the other terms may also indicate a specific
version of a file, but may also refer to the commits.
PatrickThere was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): >> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
>> +cherry-pick`, `git pull`, or `git revert`. All of those commands use
>
> Should all of these be using linkgit:, like for example in
> linkgit:git-merge[1]?
Makes sense to me, will change.
>> +The most common ways to handle a merge conflict are:
>> +
>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
>> + below for details)
>> +* Or stop the operation and return your branch to its original state
>> + with the appropriate `--abort` command, for example `git merge --abort`
>> + or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
>> + for how to find the command to run.
>
> I wonder whether the explanation should be expanded a bit to briefly
> explain how Git performs a 3-way merge in the first place. I feel like
> it's quite important to understand what the three different sides of the
> merge are to make sense of it.
>
> But I may be too far detached from the "normal" user, so this may only
> cause more confusion for our users.
I think it would cause more confusion. I did some experiments in explaining
merge conflicts using the concept of 3-way merge a couple of years
ago and it didn't go well.
My experience was that what users they found the most useful was
learning about the tools Git offers (like `git diff --check` and `diff3`),
so that's why this document focuses on tools and formatting much
more than concepts.
I think it would be cool to find a way to explain how 3-way merge works at in
this document in some later iteration though, maybe at the end. Definitely some
folks would find it interesting. I didn't understand 3-way merge myself until a
couple of years ago and it was fun for me to learn, but it didn't really help me
use Git effectively.
(this is quickly becoming a bit of a novel, but it's often very counterintuitive
how some facts that seem "fundamental" about how Git works actually turn
out to not be very important to understand in practice to use it effectively.
It's something I find tough to talk about on this mailing list because it's something
I've only been able to learn empirically)
>> +[[markers]]
>> +MERGE CONFLICT MARKERS
>> +----------------------
>> +
>> +Merge conflicts happen when both of the sides being merged edit the same
>> +area of a file. When this happens, Git will update the conflicted file
>
> I wonder whether we want to use "hunk" instead of "area". It's jargon
> again, but I have never heard anybody speak about an "area" before
> myself.
Ah thanks, I think I took "area" from the `git-merge` man page.
I looked up how I explained this previously and I used "lines of code",
which I think communicates the same meaning without the jargon.
I'll try that instead.
>> +Note: During a `git merge`, `git commit` and `git merge --continue` do
>> +the the same thing.
>
> s/the the/the/
Will fix.
>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
>> +For example, here's a merge conflict where both sides edited a list of
>> +fruits in different ways:
>> +
>> +----
>> +FRUITS = [
>> + "apple",
>> +<<<<<<< HEAD
>> + "cherry",
>> +=======
>> + "banana",
>> +>>>>>>> add-fruit
> Hide quoted text
>
> A bit of a tangent, but sometimes I wonder whether we should make the
> respective commits a bit easier to access. For example, we could put the
> equivalent of `git rev-parse --reference <commit>` here for each of the
> sides.
Personally I'm not sure if the commit ID would do much for me, but I feel
like it would help me if it were possible to include the commit message.
> I tend to forget that by default, we only render ours/theirs in the
> conflict. I always feel like that makes it way harder to resolve
> conflicts as you don't have the context of what the code looked like
> originally. So I have diff3 configured locally for ages.
Every time I show people diff3 someone tells me how happy they
are to learn it :)
>> +* There are many graphical "merge tools" for Git, which will normally
>> + show you the different versions of the code side by side.
>> + If you have a mergetool configured, `git mergetool` will launch it.
>> + See also `merge.tool` in linkgit:git-config[1] for a list of
>> + the mergetools Git supports.
>
> There's also `git merge-tool --tool-help` to list all available drivers.
Oh, cool! It's fun that it autodetects which ones you have installed
on your system. I'll suggest that.
>
> [snip]
>> +[[ours]]
>> +"OURS" AND "THEIRS"
>> +-------------------
>> +
>> +Git refers to the first part of a merge conflict (between `<<<<<<<`
>> +and `=======`) as "ours" and the second part (between `=======` and
>> +`>>>>>>>`) as "theirs".
>> +
>> +Normally, "ours" is the commit that was checked out before you started
>> +the merge, and "theirs" is the other commit.
>> +
>> +But when the merge conflict was caused by a `git rebase`, it's the
>> +opposite: "theirs" is the commit that was checked out before you started
>> +the merge. This is because under the hood, `git rebase main` checks out
>> +the `main` commit first before doing the merge operation.
>
> Hmm. This part is a bit confusing to me. "ours" is always the commit
> that's currently checked out, and "theirs" is always the one that is
> getting merged into the checked-out commit.
>
> How about a variant of the following instead?
>
> In a conflict, the side between `<<<<<<<` and `=======` is "ours"
> and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is
> always the side that `HEAD` points to while the merge happens; "theirs"
> is the commit being merged into it.
>
> For `git merge <other>`, `HEAD` is your current branch, so "ours" is
> your branch and "theirs" is `<other>`.
>
> For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and
> your commits are then replayed on top one at a time. So "ours" is the
> already-rebased history starting at `<upstream>`, and "theirs" is the
> commit from your original branch that is currently being replayed.
Thanks, your suggestion gives me some other ways to think about this.
I think I'll try to write something shorter that is unambiguous, instead of trying
to use more words to make it feel more intuitive. I don't think I actually know
anyone who feels it's easy to understand the way merge conflicts are
presented, and more explanation may not help.
It might be more useful here to encourage (again) folks to use one of the many
amazing tools available (in the "tools" section) to get more context.
>> +These terms in Git all mean the same thing when dealing with a merge
>> +conflict:
>> +
>> +* "common ancestor", "base", and "stage 1"
>> +* "ours", "us", "stage 2", and `HEAD`
>> +* "theirs", "them", and "stage 3"
>
> I wouldn't say that "stage N" is equivalent to the respective other
> terms. These stages rather refer to the different versions of a specific
> file as recorded in the index, they do not indicate a specific commit.
> In contrast to that, all the other terms may also indicate a specific
> version of a file, but may also refer to the commits.
Thanks, will try to figure out how to make it more accurate.
We could also refer to gitdatamodel if folks want to learn what the
term "stage" means too.
Thanks for the review!
- JuliaThere 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:
>>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
>>> +For example, here's a merge conflict where both sides edited a list of
>>> +fruits in different ways:
>>> +
>>> +----
>>> +FRUITS = [
>>> + "apple",
>>> +<<<<<<< HEAD
>>> + "cherry",
>>> +=======
>>> + "banana",
>>> +>>>>>>> add-fruit
>> Hide quoted text
>>
>> A bit of a tangent, but sometimes I wonder whether we should make the
>> respective commits a bit easier to access. For example, we could put the
>> equivalent of `git rev-parse --reference <commit>` here for each of the
>> sides.
>
> Personally I'm not sure if the commit ID would do much for me, but I feel
> like it would help me if it were possible to include the commit message.
It would also help the resolution, not just committing after you are
done. It may not matter while picking between cherry and banana to
show your personal preference on fruits, but in a more involved
conflicted merge, it may help to be able to view "git show $commit",
"git diff ...$commit", and "git diff $commit..." where $commit is
the "add-fruit" side of the merge to understand what they wanted to
do, and what we have done while they weren't looking.
>> I tend to forget that by default, we only render ours/theirs in the
>> conflict. I always feel like that makes it way harder to resolve
>> conflicts as you don't have the context of what the code looked like
>> originally. So I have diff3 configured locally for ages.
>
> Every time I show people diff3 someone tells me how happy they
> are to learn it :)
Yes, we should encourage "merge.conflictstyle=diff3" (I feel about
this strongly enough to think it should become the default).
Knowing what the original was before one side wanted to say "cherry"
while the other side wanted to say "banana" sometimes helps a great
deal to decide what to do with the conflict.There was a problem hiding this comment. Patrick Steinhardt wrote on the Git mailing list (how to reply to this email): On Wed, Sep 30, 2026 at 01:37:16PM -0700, Junio C Hamano wrote:
> "Julia Evans" <julia@jvns.ca> writes:
>
> >>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
> >>> +For example, here's a merge conflict where both sides edited a list of
> >>> +fruits in different ways:
> >>> +
> >>> +----
> >>> +FRUITS = [
> >>> + "apple",
> >>> +<<<<<<< HEAD
> >>> + "cherry",
> >>> +=======
> >>> + "banana",
> >>> +>>>>>>> add-fruit
> >> Hide quoted text
> >>
> >> A bit of a tangent, but sometimes I wonder whether we should make the
> >> respective commits a bit easier to access. For example, we could put the
> >> equivalent of `git rev-parse --reference <commit>` here for each of the
> >> sides.
> >
> > Personally I'm not sure if the commit ID would do much for me, but I feel
> > like it would help me if it were possible to include the commit message.
>
> It would also help the resolution, not just committing after you are
> done. It may not matter while picking between cherry and banana to
> show your personal preference on fruits, but in a more involved
> conflicted merge, it may help to be able to view "git show $commit",
> "git diff ...$commit", and "git diff $commit..." where $commit is
> the "add-fruit" side of the merge to understand what they wanted to
> do, and what we have done while they weren't looking.
Yup. Doesn't mean we cannot _also_ include the names that we have above.
So in the above example it could be for example:
+FRUITS = [
+ "apple",
+<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01)
+ "cherry",
+=======
+ "banana",
+>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03)
That format would have a bunch of advantages:
- We don't have to teach users about special refs like MERGE_HEAD to
let them figure out how to access each of the commits.
- It gives a bit more context about what each specific side does, at
least if you have good commit messages.
- It also gives a sense of timing because we include dates, and that
may help in some situations to figure out what's what.
I'll create an issue on the GitLab side and ask someone in the team to
maybe give this a try.
> >> I tend to forget that by default, we only render ours/theirs in the
> >> conflict. I always feel like that makes it way harder to resolve
> >> conflicts as you don't have the context of what the code looked like
> >> originally. So I have diff3 configured locally for ages.
> >
> > Every time I show people diff3 someone tells me how happy they
> > are to learn it :)
>
> Yes, we should encourage "merge.conflictstyle=diff3" (I feel about
> this strongly enough to think it should become the default).
> Knowing what the original was before one side wanted to say "cherry"
> while the other side wanted to say "banana" sometimes helps a great
> deal to decide what to do with the conflict.
I very much agree that it should be the default.
PatrickThere was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): > +FRUITS = [
> + "apple",
> +<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01)
> + "cherry",
> +=======
> + "banana",
> +>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03)
>
> That format would have a bunch of advantages:
>
> - We don't have to teach users about special refs like MERGE_HEAD to
> let them figure out how to access each of the commits.
>
> - It gives a bit more context about what each specific side does, at
> least if you have good commit messages.
>
> - It also gives a sense of timing because we include dates, and that
> may help in some situations to figure out what's what.
This is so cool, I love the idea of including the dates and the commit
messages!!! I think this would be very helpful for the reasons you say.
Though re "We don't have to teach users about special refs
like MERGE_HEAD": I think that users today could run`git show HEAD`
or `git show add-fruit` to see the commits on each side? I've never
used MERGE_HEAD though so maybe I'm misunderstanding what
it does. I think adding the commit ID makes it clearer too.
I just ran downstairs to show my partner this example at 8am
because I was so excited about it :) (he liked it too)There was a problem hiding this comment. Junio C Hamano wrote on the Git mailing list (how to reply to this email): Junio C Hamano <gitster@pobox.com> writes:
>>>> +FRUITS = [
>>>> + "apple",
>>>> +<<<<<<< HEAD
>>>> + "cherry",
>>>> +=======
>>>> + "banana",
>>>> +>>>>>>> add-fruit
>
>> Every time I show people diff3 someone tells me how happy they
>> are to learn it :)
>
> Yes, we should encourage "merge.conflictstyle=diff3" (I feel about
> this strongly enough to think it should become the default).
> Knowing what the original was before one side wanted to say "cherry"
> while the other side wanted to say "banana" sometimes helps a great
> deal to decide what to do with the conflict.
Before I forget, here is a good illustration to tell why diff3 style
is often essential to correct conflict resolution that we can tell
new users. You may want to throw it in to your new manual pages.
If the conflict looks like this
FRUITS = [
"apple",
<<<<<<< HEAD
"cherry",
|||||||
=======
"banana",
>>>>>>> add-fruit
then we can tell that in the beginning there was only 'apple', and
one side wanted to add 'cherry', while the other side wanted to add
'banana'. It is likely that we would make both sides happy by
adding both of them.
But on the other hand, if the conflict looks like this
FRUITS = [
"apple",
<<<<<<< HEAD
"cherry",
|||||||
"banana",
"cherry",
=======
"banana",
>>>>>>> add-fruit
we can tell that before two sides started editing, we had 'apple',
'banana', and 'cherry'. While both wanted to keep 'apple', one side
did not want 'banana', and the other side did not want 'cherry'. It
is plausible that we can please both of them by removing these two.
With just two-sides, the user who is trying to resolve the conflict
cannot tell the difference. |
||
| MAN7_TXT += gitfaq.adoc | ||
| MAN7_TXT += gitglossary.adoc | ||
| MAN7_TXT += gitmergeconflicts.adoc | ||
| MAN7_TXT += gitpacking.adoc | ||
| MAN7_TXT += gitnamespaces.adoc | ||
| MAN7_TXT += gitremote-helpers.adoc | ||
|
|
||
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
> ---There was a problem hiding this comment. "Julia Evans" wrote on the Git mailing list (how to reply to this email): > The new document may explain how to resolve conflicts, but are the
> details removed from here that are specific to the 'cherry-pick'
> operation also covered there?
I'll update this series to make fewer changes to this page as you
suggest to make the diff smaller.
> For example, during a difficult cherry-pick, it is often handy to be
> able to run 'git show CHERRY_PICK_HEAD', but now users are not told
> about the pseudo-ref, which seems like a real loss.
I'll put this back for now, but I removed it because I couldn't
understand why CHERRY_PICK_HEAD might be useful, and some of my user research
showed that almost nobody uses `CHERRY_PICK_HEAD`. I always appreciate people
telling me why these things are actually useful though, and even if very few
people use something, maybe more people would use it if it was clear why it's
useful :)
My best guess (based on what you said) is that `CHERRY_PICK_HEAD` is
only useful if you're cherry-picking multiple commits at the same time.
Is the following an accurate explanation?:
> If the conflict happened when cherry picking multiple commits, you can run
> `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply.
> The fact that cleanly auto-resolved contents for paths are recorded
> in the index may be shared with all other merge-like operations,
> and it need not be part of the "how to resolve a conflicted
> merge-like operation" recipe, but users need to be assured that this
> is what happens somewhere in the documentation set. The list
> removed here served that purpose for this specific command, but it
> is now gone.
That makes sense to me. One major benefit of making a
centralized page is that each man page explains different aspects
of the merge conflict process, and we can make sure that anyone
who needs to solve a merge conflict is aware of all the aspects.
I'll think about how to explain that.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:
> My best guess (based on what you said) is that `CHERRY_PICK_HEAD` is
> only useful if you're cherry-picking multiple commits at the same time.
> Is the following an accurate explanation?:
>
>> If the conflict happened when cherry picking multiple commits, you can run
>> `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply.
You do not have to limit yourself to the multi-pick case. If you
make it a habit to use CHERRY_PICK_HEAD, you do not have to remember
exactly which commit you specified on the command line to pick when
stopped by a conflict during a cherry-pick. This is especially true
for those who have already made it a habit to use MERGE_HEAD when
stopped by a conflict during a merge. Not having to think when you
can mechanically perform a routine task is bliss.
|
||
| 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): "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.
There was a problem hiding this comment. "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.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:
>> - "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.
;-).There was a problem hiding this comment. "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 KnobleThere was a problem hiding this comment. 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.
There was a problem hiding this comment. Patrick Steinhardt wrote on the Git mailing list (how to reply to this email): On Thu, Sep 24, 2026 at 02:44:17PM +0000, Julia Evans via GitGitGadget wrote:
> From: Julia Evans <julia@jvns.ca>
>
> All of the info about merge conflicts has been moved to the new guide
Pedantic nit: missing punctuation.
Other than that I agree with Ben, one part that we lose here is some
context on what a merge conflict even is.
Patrick |
||
| 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):