[doc] Add new page on merge conflicts by jvns · Pull Request #2237 · gitgitgadget/git

jvns · 2026-09-23T10:49:40Z

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

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

Changed in v2:

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

Changed in v3:

unsure:

the wording of "When Git merges two commits together" is a bit weird but we don't have a better idea right now (Junio)
"return your branch to its original state" -> maybe remove "your branch" bc the branch was never changed (ask marie) (Junio)
look at order of sentences when introducing AUTO_MERGE (Junio)
"The most common ways to handle a merge conflict are:" is a bit weaselly (junio)
maybe replace "configuration option" with "configuration variable" (junio)

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 · 2026-09-23T10:50:18Z

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

Commit not signed off

gitgitgadget · 2026-09-23T10:50:19Z

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

Commit not signed off

gitgitgadget · 2026-09-23T10:50:19Z

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

Commit not signed off

gitgitgadget · 2026-09-23T10:50:20Z

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 · 2026-09-23T10:50:21Z

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

Commit not signed off

gitgitgadget · 2026-09-23T10:50:22Z

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 · 2026-09-23T15:48:51Z

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 · 2026-09-23T15:56:23Z

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 · 2026-09-23T17:30:53Z

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

dscho · 2026-09-23T17:33:54Z

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 · 2026-09-23T17:36:01Z

thanks, appreciate your work on testing!

jvns · 2026-09-23T17:43:55Z

/preview

gitgitgadget · 2026-09-23T17:45:11Z

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

jvns · 2026-09-24T14:43:06Z

/submit

gitgitgadget · 2026-09-24T14:45:29Z

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 · 2026-09-24T20:26:25Z

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

gitgitgadget · 2026-09-24T22:13:38Z

@@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc
 MAN7_TXT += giteveryday.adoc


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,

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 · 2026-09-25T00:34:34Z

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 · 2026-09-25T00:34:54Z

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 · 2026-09-25T00:34:56Z

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

gitgitgadget · 2026-09-25T19:21:46Z

"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 · 2026-09-25T19:21:49Z

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

gitgitgadget · 2026-09-25T19:22:02Z

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


"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

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

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.

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

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.

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.

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

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

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

On Fri, Oct 2, 2026 at 1:01 PM Julia Evans <julia@jvns.ca> wrote: > > > > On Fri, Sep 25, 2026, at 12:59 PM, Julia Evans wrote: > > On Fri, Sep 25, 2026, at 12:36 PM, D. Ben Knoble wrote: > >> Hi Julia, > >> > >> On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget > >> <gitgitgadget@gmail.com> wrote: > >>> > >>> From: Julia Evans <julia@jvns.ca> > >>> > >>> All of the info about merge conflicts has been moved to the new guide > >> > >>> Among the changes made to the common ancestor's version, > >>> -non-overlapping ones (that is, you changed an area of the file while the > >>> -other side left that area intact, or vice versa) are incorporated in the > >>> -final result verbatim. When both sides made changes to the same area, > >>> -however, Git cannot randomly pick one side over the other, and asks you to > >>> -resolve it by leaving what both sides did to that area. > > >> I think these are both valuable pieces of information we have lost in > >> the new guide (unless I misremember just having read patch 1 :). > >> > >> The first explains a bit more about what a conflict *is*. Maybe that's > >> old-hat nowadays, but I think it could be nice to keep a statement > >> about why conflicts exist. > > > > Will think about this! > > After talking this through with my collaborator Marie, we wrote a new > "what is a merge conflict?" section which I'll include in the v2. > > Like I mentioned before elsewhere it takes a super light approach to > introducing the 3-way merge. (there is intentionally no mention > of "since they diverged from the common ancestor" etc) > > WHAT IS A MERGE CONFLICT? > ------------------------- > > When Git merges two commits together, it looks at the changes that > each side has made and combines those changes. For example, if one side > edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of > `hello.py`, then it can easily combine them. > > But if both sides edited overlapping lines of the same file (for example > one side edited lines 1-5 and the other edited lines 3-6), Git will > not try to guess how to combine those changes. This is called a "merge > conflict". > > When this happens, Git shows you both sides' edits and asks you to pick > how to resolve them. It: > > * Stages all of the files which were successfully merged > * For the files with conflicts, it leaves them unstaged, puts both > sides' edits in the file, and leaves <<markers, merge conflict markers>> > that you need to resolve. > I quite like this. I'm sure it oversimplifies somewhere, but at least I personally cannot immediately see where (or how it does any harm to) ;) Thanks! PS Unlike Junio---perhaps due to my lack of older Git history and terminology, despite using Git since 2016?---I would never have read "unstaged" as *deleted* from the index. Just changed and not updated in the index (i.e., not "git add"-ed). -- D. Ben Knoble

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

"D. Ben Knoble" <ben.knoble@gmail.com> writes: > PS Unlike Junio---perhaps due to my lack of older Git history and > terminology, despite using Git since 2016?---I would never have read > "unstaged" as *deleted* from the index. Just changed and not updated > in the index (i.e., not "git add"-ed). I agree such an interpretation is certainly possible. The verb "to unstage" would be the opposite of "to stage", but it is ambiguous what kind of oppositeness you want to express. This is unlike "to stage" whose possible interpretation is fairly narrow. You register the contents that you consider desirable for the path using various means. On the other hand, "to unstage" is undoing the result of your earlier act "to stage", but it may mean reverting to what is recorded in HEAD (i.e., "git reset HEAD -- path"), undoing the fact that you added a path to the index (i.e., "git rm --cached -- path"). Neither interpretation is what you want when talking about what a conflicted merge does to remember the three stages for a conflicted path in the index. Hence my suggestion to avoid using the verb.

gitgitgadget · 2026-10-06T01:30:51Z

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

On Fri, Oct 2, 2026, at 10:29 PM, D. Ben Knoble wrote:
> On Fri, Oct 2, 2026 at 1:40 PM Julia Evans <julia@jvns.ca> wrote:
>>
>> Thanks for the review!
>>
>> >>  * 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
>>
>> Wow, that's a very interesting read. I'm more informed than I was before
>> I read it but also at the same time more confused :). It makes me think
>> that "git commit does the same thing as git merge --continue" is maybe
>> not true but also I don't know what the difference might be.
>>
>> I've put an item on my TODO list to remove
>> `git commit does the same thing as git merge --continue`" and to try to
>> replace it with a more vague sentence that I guess says you can use
>> either command without being so specific on whether they are exactly
>> the same.
>
> For now I would say the subtleties in that conversation really make me
> lean towards the following:
>
> - "git <thing> --continue" is, for most users in most cases, the right
> thing to do. It's what "git status" recommends and will practically
> never do anything surprising (?).

I was actually surprised to discover that `git status` does not recommend
`git merge --continue`: it recommends `git commit`.
Maybe we should change that though?

I agree it makes sense to be consistent with what `git status` recommends.

> - However, it may not always be exactly what you *want*---and you'll
> usually know when you want to go "outside" the normal sequencer and
> commit directly (because you'll have understood some nuanced details
> about what can happen).
>
> For merge it may be the case that they're the same, I suppose (I'm
> genuinely not sure), but I would prefer to simplify folks' paths by
> recommending one of the few uniform interfaces we have :)

The only other thing that gives me pause about recommending folks
`git merge --continue` too strongly is that as we know Git users are slow to
change their habits, and we don't want to confuse anyone. If someone is
currently using `git commit` I want to know that they can keep doing
it the same way with no worries.

Maybe if we change `git status` to recommend `git merge --continue`,
and we think there are no real advantages to using `git commit` instead
of `git merge --continue`, then we could say something like this:

  NOTE: `git commit` is an older alternative to `git merge --continue`.
  You can use either one after resolving a `git merge`.

gitgitgadget · 2026-10-06T01:31:39Z

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

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

Expecting a reroll.
cf. <5ba2088c-4919-465f-8892-4ed0685f81ea@app.fastmail.com>
cf. <2f71028f-d58e-400f-a02e-7a25c032d889@app.fastmail.com>
source: <pull.2237.git.1790261062.gitgitgadget@gmail.com>

gitgitgadget · 2026-10-06T20:09:48Z

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

On Mon, Oct 5, 2026 at 2:50 PM Julia Evans <julia@jvns.ca> wrote:
> >
> > For now I would say the subtleties in that conversation really make me
> > lean towards the following:
> >
> > - "git <thing> --continue" is, for most users in most cases, the right
> > thing to do. It's what "git status" recommends and will practically
> > never do anything surprising (?).
>
> I was actually surprised to discover that `git status` does not recommend
> `git merge --continue`: it recommends `git commit`.

Wow, yeah! I'm surprised, too. (See
wt-status.c:show_merge_in_progress(), and compare with other related
functions.)

> Maybe we should change that though?

I think so, at least.

> I agree it makes sense to be consistent with what `git status` recommends.

For sure.

> > - However, it may not always be exactly what you *want*---and you'll
> > usually know when you want to go "outside" the normal sequencer and
> > commit directly (because you'll have understood some nuanced details
> > about what can happen).
> >
> > For merge it may be the case that they're the same, I suppose (I'm
> > genuinely not sure), but I would prefer to simplify folks' paths by
> > recommending one of the few uniform interfaces we have :)
>
> The only other thing that gives me pause about recommending folks
> `git merge --continue` too strongly is that as we know Git users are slow to
> change their habits, and we don't want to confuse anyone. If someone is
> currently using `git commit` I want to know that they can keep doing
> it the same way with no worries.
>
> Maybe if we change `git status` to recommend `git merge --continue`,
> and we think there are no real advantages to using `git commit` instead
> of `git merge --continue`, then we could say something like this:
>
>   NOTE: `git commit` is an older alternative to `git merge --continue`.
>   You can use either one after resolving a `git merge`.

That sounds like a reasonable plan. Another plan that occurs to me is
to go forward with the "commit" version (for merges; other commands
should use the sequencer versions that status recommends) and update
this doc later if we do change status to recommend "merge --continue".

I'd love to hear from others on either changing status output to
recommend "merge --continue" or admitting that, for merges, "commit"
is the same thing.

-- 
D. Ben Knoble

gitgitgadget · 2026-10-06T20:09:54Z

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

On Tue, Oct 6, 2026 at 12:53 PM D. Ben Knoble <ben.knoble@gmail.com> wrote:
>
> I'd love to hear from others on either changing status output to
> recommend "merge --continue" or admitting that, for merges, "commit"
> is the same thing.

I see now there's a patch in-flight (downside of reading mail oldest
to newest). I'll expect to discuss this particular point there,
thanks!

-- 
D. Ben Knoble

gitgitgadget · 2026-10-07T13:47:17Z

There is an issue in commit b32bf50:
doc: Add new gitmergeconflicts man page

Prefixed commit message must be in lower case

gitgitgadget · 2026-10-07T13:50:37Z

There is an issue in commit 0d54ca9:
doc: Add new gitmergeconflicts man page

Prefixed commit message must be in lower case

Introduce a new page, `gitmergeconflicts`, that explains the process of handling a merge conflict in a way that addresses the following issues, which came from feedback from Git users on the current explanation of merge conflicts in the `git merge` man page: - The process for resolving a merge conflict is only explained in the `git merge` man page, even though there are several other commands which can result in conflicts - Sometimes we use "ours" and "theirs" to refer to the two sides of the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should be consistent. Also the terms "ours" and "theirs" are not explained. Similarly, it says "The part before the `=======` is typically your side...", but doesn't explain what "typically" means. - It introduces the merge format using an analogy to RCS, which very few Git users have ever used - In "The only clean-ups you need are to reset the index file to the `HEAD` commit to reverse 2. and to clean up working tree changes made by 2. and 3.", it's not clear to users what "2" and "3" are supposed to mean - It uses a cultural reference ("Conflict resolution is hard; let's go shopping.") which is confusing or unfamiliar to some people. I think it would be clearer for users to use a code example instead. - It doesn't explain the difference between diff3 and zdiff3 - It sometimes uses the term "area" and sometimes uses the term "hunk" Also document the unified `--abort`, `--continue` workflow in one place, since it's a really nice example of a place Git has a consistent interface between similar commands. Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com> Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com> Reviewed-by: Patrick Steinhardt <ps@pks.im> Signed-off-by: Julia Evans <julia@jvns.ca>

All of the info about merge conflicts has been moved to the new guide Signed-off-by: Julia Evans <julia@jvns.ca>

Remove some of the detail about how to handle a merge conflict, since it's explained in detail in the new guide, and there probably isn't enough detail anyway. Leave the steps since rebase is special and has a `--skip` option which the other commands which cause merge conflicts don't have. Signed-off-by: Julia Evans <julia@jvns.ca>

Signed-off-by: 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>

Signed-off-by: Julia Evans <julia@jvns.ca>

gitgitgadget · 2026-10-07T21:36:42Z

@@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace
 /t/oid-info/* text eol=lf


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

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes: > Subject: Re: [PATCH 7/7] [doc] ignore conflict markers in gitmergeconflicts.adoc > From: Julia Evans <julia@jvns.ca> > > Signed-off-by: Julia Evans <julia@jvns.ca> > --- > .gitattributes | 1 + > 1 file changed, 1 insertion(+) > > diff --git a/.gitattributes b/.gitattributes > index 26490ad60a..0a0fc950b1 100644 > --- a/.gitattributes > +++ b/.gitattributes > @@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace > /t/oid-info/* text eol=lf > /Documentation/git-merge.adoc conflict-marker-size=32 > /Documentation/git-merge-file.adoc conflict-marker-size=32 > +/Documentation/gitmergeconflicts.adoc conflict-marker-size=32 > /Documentation/gitk.adoc conflict-marker-size=32 > /Documentation/user-manual.adoc conflict-marker-size=32 > /t/t????-*.sh conflict-marker-size=32 The title of this patch seems to show a fundamental misunderstanding of what these custom conflict marker settings mean. I believe the plan is to squash this into the step that introduces the new file; when that happens, the patch title will disappear and we will not have to worry about it, but regardless. Setting a custom 'conflict-marker-size' is not about ignoring anything. It ensures that payload lines that happen to look like conflict markers are not mistaken for them. Machinery like rerere parses conflicted files, and you do not want it to mistake a run of seven '<' characters at the beginning of a line you deliberately wrote as the start of a conflict block. You prevent such mistakes by specifying that the conflict delimiter used during conflicts will be N (!= 7) characters long, instead of the regular seven. By the way, some of the points above might be worth teaching in the material covering merge conflicts (i.e., this series). I do not think many people write manuals on Git with examples of what a conflict block looks like ;-), but a run of seven '<', '=', '|', or '>' characters may appear in real payloads that users need to use, in contexts completely unrelated to ours. Setting 'conflict-marker-size' to a length that their payload is unlikely to use is a useful technique to be aware of. Thanks.

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

On Wed, Oct 7, 2026, at 5:21 PM, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> Subject: Re: [PATCH 7/7] [doc] ignore conflict markers in gitmergeconflicts.adoc >> From: Julia Evans <julia@jvns.ca> >> >> Signed-off-by: Julia Evans <julia@jvns.ca> >> --- >> .gitattributes | 1 + >> 1 file changed, 1 insertion(+) >> >> diff --git a/.gitattributes b/.gitattributes >> index 26490ad60a..0a0fc950b1 100644 >> --- a/.gitattributes >> +++ b/.gitattributes >> @@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace >> /t/oid-info/* text eol=lf >> /Documentation/git-merge.adoc conflict-marker-size=32 >> /Documentation/git-merge-file.adoc conflict-marker-size=32 >> +/Documentation/gitmergeconflicts.adoc conflict-marker-size=32 >> /Documentation/gitk.adoc conflict-marker-size=32 >> /Documentation/user-manual.adoc conflict-marker-size=32 >> /t/t????-*.sh conflict-marker-size=32 > I believe the > plan is to squash this into the step that introduces the new file; > when that happens, the patch title will disappear and we will not > have to worry about it Yes, I squashed it in the new version. I don't share your opinions about how the title of this patch was worded but it's such a minor point that I don't think it's worth discussing. > By the way, some of the points above might be worth teaching in the > material covering merge conflicts (i.e., this series). I do not > think many people write manuals on Git with examples of what a > conflict block looks like ;-), but a run of seven '<', '=', '|', or > '>' characters may appear in real payloads that users need to use, > in contexts completely unrelated to ours. > > Setting 'conflict-marker-size' to a length that their payload is > unlikely to use is a useful technique to be aware of. I do not think that would be useful to explain in this series. (since as you say Git's situation is unusual and it's not a good practice to explain things that we don't think are relevant "just in case"). If users ask for it to be covered in the future we can add it then.

gitgitgadget · 2026-10-08T01:17:15Z

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

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

Expecting a reroll.
cf. <e593f3ca-4a03-45a7-b0cc-6295a3a4939f@app.fastmail.com>
source: <pull.2237.git.1790261062.gitgitgadget@gmail.com>

jvns · 2026-10-09T11:59:18Z

/submit

gitgitgadget · 2026-10-09T12:01:11Z

Submitted as pull.2237.v2.git.1791547213.gitgitgadget@gmail.com

To fetch this version into FETCH_HEAD:

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

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

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

gitgitgadget · 2026-10-09T19:00:16Z

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

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

>  * [x] list reviewers in Reviewed-by

We may have a bit of misunderstanding in the process regarding this.

. `Reviewed-by:`, unlike the other trailers, can only be offered by the
  reviewers themselves when they are completely satisfied with the
  patch after a detailed analysis.

is how SubmittingPatches describes it.

ReviewingGuidelines.adoc tells reviewers

  If you are happy with the state of the patch series, explicitly
  indicate your approval (typically with a reply to the latest
  version's cover letter). Optionally, you can let the author know
  that they can add a "Reviewed-by: <you>" trailer if they resubmit
  the reviewed patch verbatim in a later iteration of the series.

For example, you added Ben and Patrick to the trailer of patch #1.

> Range-diff vs v1:
>
>  1:  ad4853dc36 ! 1:  ab0344f947 [doc] Add new gitmergeconflicts man page
>      @@ Metadata
>       Author: Julia Evans <julia@jvns.ca>
>       
>        ## Commit message ##
>      -    [doc] Add new gitmergeconflicts man page
>      +    doc: add new gitmergeconflicts man page
> ...
>           Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
>      +    Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>
>      +    Reviewed-by: Patrick Steinhardt <ps@pks.im>
>           Signed-off-by: Julia Evans <julia@jvns.ca>

Going back to the review thread of the previous round of this patch,
https://lore.kernel.org/git/ar3sGzEknG2_Un_E@pks.im/

2026-09-24 14:44 ` [PATCH 1/7] [doc] Add new gitmergeconflicts man page Julia Evans via GitGitGadget
2026-09-24 20:36   ` Junio C Hamano
2026-09-24 22:04     ` Junio C Hamano
2026-09-30 13:19   ` Patrick Steinhardt
2026-09-30 19:53     ` Julia Evans
2026-09-30 20:37       ` Junio C Hamano
2026-10-01  5:14         ` Patrick Steinhardt [this message]
2026-10-01 12:10           ` Julia Evans
2026-10-02 17:58         ` Junio C Hamano
2026-10-05 16:54       ` Julia Evans
2026-10-05 17:22         ` Junio C Hamano
2026-10-05 19:11           ` Julia Evans

There are many messages that reply to the cover letter of the same
iteration by Ben that gave a lot of good input, and I know Patrick
also helped during the discussion to improve the document.  I do not
think neither of them said anything about reviewed-by.

We do want to credit the reviewers of previous rounds for their
input that contributed to improvements in the latest round.  But the
way to do so is by mentioning them on "Helped-by:" you add.

Thanks.

gitgitgadget · 2026-10-09T19:00:20Z

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

On Fri, Oct 9, 2026, at 11:41 AM, Junio C Hamano wrote:
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>>  * [x] list reviewers in Reviewed-by
>
> We may have a bit of misunderstanding in the process regarding this.
>
> . `Reviewed-by:`, unlike the other trailers, can only be offered by the
>   reviewers themselves when they are completely satisfied with the
>   patch after a detailed analysis.
>
> is how SubmittingPatches describes it.

Thanks, put this in my todo list to fix in the next round.
I'll use Helped-by instead.

gitgitgadget · 2026-10-09T19:00:34Z

@@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace
 /t/oid-info/* text eol=lf


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> > > Introduce a new page, `gitmergeconflicts`, that explains the process of > handling a merge conflict in a way that addresses the following issues, > which came from feedback from Git users on the current explanation of > merge conflicts in the `git merge` man page: Good goal. > - The process for resolving a merge conflict is only explained in the > `git merge` man page, even though there are several other commands > which can result in conflicts > - Sometimes we use "ours" and "theirs" to refer to the two sides of > the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should > be consistent. Also the terms "ours" and "theirs" are not explained. > Similarly, it says "The part before the `=======` is typically your > side...", but doesn't explain what "typically" means. > - It introduces the merge format using an analogy to RCS, which very few > Git users have ever used > - In "The only clean-ups you need are to reset the index file to the > `HEAD` commit to reverse 2. and to clean up working tree changes made > by 2. and 3.", it's not clear to users what "2" and "3" are supposed > to mean > - It uses a cultural reference ("Conflict resolution is hard; let's go > shopping.") which is confusing or unfamiliar to some people. I think it > would be clearer for users to use a code example instead. > - It doesn't explain the difference between diff3 and zdiff3 > - It sometimes uses the term "area" and sometimes uses the term "hunk" It is a bit hard to evaluate this list, as we do not see any of the above problems excised from the existing documents in this step. But at least we can verify that the new text presented in this patch does not fall into the same trap as above, so I'll keep that in mind while reviewing this step. > Also document the unified `--abort`, `--continue` workflow in one > place, since it's a really nice example of a place Git has a consistent > interface between similar commands. Great. > Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com> > Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com> > Reviewed-by: Patrick Steinhardt <ps@pks.im> > Signed-off-by: Julia Evans <julia@jvns.ca> We want a sign-off by the coauthor, too. > diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc > new file mode 100644 > index 0000000000..5b0ba1a1de > --- /dev/null > +++ b/Documentation/gitmergeconflicts.adoc > @@ -0,0 +1,333 @@ > +gitmergeconflicts(7) > +==================== > + > +NAME > +---- > +gitmergeconflicts - 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 > +the same merge algorithm, and the process for resolving a merge conflict > +is always very similar. Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order tolimit ourselves to most common ways to help new people by keeping the description to the absolute minimum? Or were they just overlooked? In any case, the first paragraph clearly stating that conflicts happen with operations other than 'merge' is a very welcome change. On this list, we often say "mergy operations can cause conflicts", with the understanding that readers know what mergy operations are and "conflicts" alone can convey the state you call "merge conflicts" in this document. But in a document for end-users, using a longer term "merge conflicts" instead of "conflicts" and avoiding "mergy operations" like you did above may be a better direction to go. > +The most common ways to handle a merge conflict are: A natural paraphrase of the above is "A merge conflict is typically handled by these ways", but I thought the current readers are puzzled by "typically your side" that does not say when is typical. > +* 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. Both are good options and I do not think of a middle way. Perhaps we do not have to say that these are "the most common" and instead say "You handle a merge conflict by doing either of these two"? Saying "return your branch to" is a bit misleading for two reasons. Conflicts presented to the users are primarily visible in their working tree files and the index. A single commit operations like 'merge', 'pull', and 'revert' does not touch your branch if they hit a conflict, and 'rebase' works on a detached HEAD, and stops without touching your branch when it sees a conflict. If I were writing this, with the goal of avoiding the issues the current text has you listed in the proposed log message, I would probably say something like this: * Or give up and return to the original state with ... > +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 > +the same file, then it can easily combine them since there's no overlap. Many of the operations, even "git merge", is not about merging "two commits" together, but I do not think of a good way to explain it, so I accept that phrasing as a helpful white lie. I mention this because somebody else may be able to come up with a better phrasing that I (or authors of this iteration) couldn't think of. > +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 marks them as conflicted, puts both > + sides' edits in the file, and leaves <<markers, merge conflict markers>> > + that you need to resolve. By the way, I think we should briefly mention what sematnic merge conflicts are, and that Git does not detect them and that this manual page does not tell readers how to deal with them. Note that non-overlapping changes from two sides may leave the result in an inconsistent state. With the edit to lines 1-5, one side may have changed the name of a function, while with the edit to lines 20-25, the other side may have added a new call to the function by its original name. This type of inconsistencies are called semantic conflicts, Git has no way knowing that a merge introduced semantic conflicts, and ends up producing a broken result without merge conflicts. This document does not cover what to do with semantic conflicts. That is overly long, but perhaps you can condense it down to the essense and shrink down to 1/3 of the size. > +[[markers]] > +MERGE CONFLICT MARKERS > +---------------------- > + > +When there's a merge conflict, Git will update the conflicted file > +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`. I notice that when you introduce `diff3` below, you silently add `|||||||` to the mix without explaining what it is. `|||||||` may also be used as merge conflict markers (explained later). or something along the line here may help. Or explain what it is in `diff3` section. Either would work. Adding without explanation would not. > +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 > + "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. If we said "one side wanted to have 'apple, cherry, mango, orange', while the other side wanted 'apply, banana, mango, orange', in the FRUITS array", would it help the understanding? Or is it too obvious? > +[[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 same thing. > + > + > +[[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", > +] > +---- It would make your readers puzzled why the example is subtly different from the earlier one that showed "mango" as not touched by either side. I see this lays the groundwork for later demonstration of `diff3`, so having both sides explicitly want "mango" is a good example. Perhaps update the first example to be the same as this one, which would reduce the mental burden by readers? > + > +Then you might edit that part of the code like this, > +which includes the fruits from both sides of the conflict: > + > +---- > +FRUITS = [ > + "apple", > + "banana", > + "cherry", > + "mango", > + "orange", > +] > +---- OK. > +[[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. > + > +* You can set the configuration option `merge.conflictstyle=diff3`. > + See <<diff3,DIFF3 AND ZDIFF3>> below for more. These are called 'configuration variables' throughout the manual pages. Be consistent and replace "configuration option" with "configuration variable", perhaps? > +* `git log --merge -p <filename>` will list all commits which > + caused the merge conflict for `<filename>`, and the diff > + of how they changed the file. Maybe worth mentioning that `--left-right` often helps when you are not super familiar with the histories being merged. > +* Look at the original files. `git show :1:filename` shows the > + common ancestor, `git show :2:filename` shows the "ours" > + version, and `git show :3:filename` shows the "theirs" > + version. Maybe it will help to say we will explain "ours" and "theirs" later in this document. > +Here are some ways to track your progress while handling a conflict: > + > +* Use `git status` to get a list of files with conflicts > + > +* Use `git diff --check` to make sure you haven't left any merge > + conflict markers in a file by accident. It will print "leftover > + conflict marker" if it finds any. Good. This also complains about whitespace errors, by the way, but the last sentence here would be sufficient to help the readers to tell them apart. > +* Use `git diff AUTO_MERGE` to show what changes you've made so far to > + resolve the conflicts. Does a "See below" here help readers who haven't learned what AUTO_MERGE is? If you can describe what AUTO_MERGE records (in other words, what you are comparing your progress against) in a sentence of two here, that would alleviate the need to assure them that we have more in-depth coverage on this topic elsewhere. > +[[git_status]] > +EXAMPLE: GIT STATUS OUTPUT > +-------------------------- > + > +When you're in a merge conflict, you can find out what commands to run > +to handle the conflict by running `git status`. > + > +For example, this `git status` output tells you that: > + > +* `git rebase --abort` will safely bring your branch back to its > + original state > +* you should run `git rebase --continue` when you're done resolving all > + the conflicts > +* there's one file left with conflicts in it: `fruits.py` There may be users, after seeing the last point, left puzzled why fruits.py is still listed after they edited the file like instructed in an earlier example but haven't marked the resolution. `fruits.py` is not marked as its conflicts resolved yet. or something? > +---- > +$ git status > +You are currently rebasing branch 'main' on '58a9fcc'. > + (fix conflicts and then run "git rebase --continue") > + (use "git rebase --skip" to skip this patch) > + (use "git rebase --abort" to check out the original branch) > + > +Unmerged paths: > + (use "git restore --staged <file>..." to unstage) > + (use "git add <file>..." to mark resolution) > + both modified: fruits.py > +---- The approach to give explanations first and then an example the explanation explains next is refreshing to me. As long as the explanations are short enough, this may work better than the usual order to say "you'd see something like this. let us explain ...". > +[[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. I think most on the list considers `zdiff3` a failed experiment that reduces usefulness of `diff3`. Do we want to recommend it? Is it obvious to readers what "original" we are talking about? We are not talking about the state we started the mergy operation from. We are talking about what the common ancestor had before two sides started working on the text to cause the divergence that conflicted. One way I can think of to resolve this is to back to "What is a merge conflict?" section and introduce "original" right there. I'll SHOUT my additions below: When Git merges two commits together, it looks at the changes that each side has made SINCE THE TWO SIDES DIVERGED and combines those changes. WE OFTEN CALL THIS STATE THEY DIVERGED FROM THE "ORIGINAL". For example, if one side edited lines 1-5 of `hello.py` and the other side edited lines 20-25 of the same file, then it can easily combine them since there's no overlap. If you later use "common" or "common ancestor", you can explain they are "original" we defined in the above paragraph. Or ... > +Here's an example of what a merge conflict would look like when using > +`diff3`. It shows, in order, the "ours" side of the conflict, the > +original code (`"mangoooo"`), and the "theirs" side of the > +conflict. With this view, you can see that both sides fixed the spelling > +mistake in "mango", and each added one fruit to the list. ... perhaps you avoid "common ancestor" altogether, with the intention to deprecate it, and introduce "original", like in the above paragraph? That is fine too. Once we establish what to call "common, ours, theirs", we should add them to glossary-contents, as I do not think we describe any of the ones we currently use there. As I already mentioned, just like you said <<< === encloses your side and === >>> encloses their side in 2-way conflict display, we need to say <<< ||| encloses yours and ||| === encloses common in diff3 output. How theirs is shown remains the same. Here is my attempt to do so with least disruption to the flow of the text. Here is an example of what the same conflict might look with `diff3`. It uses a new separator `|||||||` before `=======`, and shows, in order the "ours" side ... > +---- > +FRUITS = [ > + "apple", > +<<<<<<< HEAD > + "cherry", > + "mango", > +||||||| 1c22e48 > + "mangoooo", > +======= > + "banana", > + "mango", > +>>>>>>> add-fruit > + "orange", > +] > +---- > + > +Here's the same example using `zdiff3`. `zdiff3` takes lines that are > +shared between both sides (the `"mango"` line) and moves them outside > +the conflicted area. This makes the conflicted area shorter, but the > +downside is that it's impossible to tell if `"mango"` was part of the > +original list of fruits or not. Yes, exactly. That is why I think we shouldn't promote it, but write it off as a failed experiment, and just tell them not to use it in this document, without giving an example. If the original were "apple, banana, cherry, mangoooo, orange", and ours and theirs were the same as the above example, then a desirable conflict resolution would be "apple, mango, orange", because both sides knew the original had banana and cherry, and each side rejected one of them each. It would be a good demonstration of why `diff3` is a better format than `(rcs)merge`, so if we were to spend lines on an example, I'd rather see it here, instead of zdiff3 example. By the way, is it just me who finds those "Here's", "there's" contractions disturbing in an official manual? I've seen many of them while reviewing this to be annoyed enough and had to blurt it out X-<. > +[[ours]] > +"OURS" AND "THEIRS" > +------------------- > + > +Sometimes during a merge conflict, Git will use the terms "ours" and > +"theirs" (or "us" and "them"). For example, `git status` might say that > +a file was `deleted by us`. OK. > +"Ours" and "theirs" are both commits: "ours" is the current > +`HEAD` commit, and "theirs" is the other side being merged. Now, "commits" is again a white lie. The story becomes more complicated when we talk about cherry-pick and revert, but if we primarily stick to what happens in 'merge' (which is what I've seen so far in this document), then it shouldn't add any extra difficulty to understand by saying "ours and theirs are history of changes leading to the two commits since they diverged from the original" to add clarity. > +The first part of a merge conflict (between `<<<<<<<` and `=======`) is > +from the "ours" side, and the second part (between `=======` and > +`>>>>>>>`) is from the "theirs" side. > + > +---- > +FRUITS = [ > + "apple", > +<<<<<<< HEAD > + "cherry", <- ours > +======= > + "banana", <- theirs > +>>>>>>> add-fruit > + "mango", > + "orange", > +] > +---- > + > +During a rebase, it can seem "upside down" because the "ours" commit is > +from the branch you're rebasing on (for instance `main` in `git rebase > +main`). > + > +These terms in Git all mean the same thing when dealing with a merge > +conflict: > + > +* "common ancestor" and "base". The files from this commit are "in stage 1". > +* "ours", "us", and `HEAD`. The files from this commit are "in stage 2". > +* "theirs", "them". The files from this commit are "in stage 3". > + > +If you're confused about what something like "deleted by us" means, it's > +often easiest to use some of the tools from > +<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context. > +Finding the commit that deleted the file and seeing why is usually more > +helpful than trying to abstractly reason through what "us" means. > + > +[[automerge]] > +EXAMPLE OF USING `AUTO_MERGE` > +----------------------------- > + > +`git diff AUTO_MERGE` will show what changes you've made so far to > +resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a > +merge. It contains the result of running the merge algorithm. The first sentence gave me "Huh? You haven't explained what AUTO_MERGE is yet". It may be just me, but I would have expected presentation order to be more like: When merge conflicts happen, the result of merge algorithm, together with conflict markers, is recorded in AUTO_MERGE. As you resolve conflicts, you can compare your working tree files against it with `git diff AUTO_MERGE` to see your progress. > +For example, if we resolved the conflict by adding both "banana" and > +"cherry" in order, the diff would look like this: > + > +---- > + FRUITS = [ > + "apple", > +-<<<<<<< HEAD > +- "cherry", > +-======= > + "banana", > +->>>>>>> add-fruit > ++ "cherry", > + "mango", > + "orange", > + ] > +---- Thanks. I was puzzled by this > - In "The only clean-ups you need are to reset the index file to the > `HEAD` commit to reverse 2. and to clean up working tree changes made > by 2. and 3.", it's not clear to users what "2" and "3" are supposed > to mean and did some digging. The text comes from ffb1a4bed5 (Documentation: Describe merge operation a bit better., 2005-11-28) that had "When there are conflicts, these things happen. 1. HEAD does not move, 2. Cleanly merged paths are updated in the index 3. Conflicts are recorded in higher stage index entries and working tree files show conflict markers, 4. No other changes are done" well before the mysterious reference to 2. and 3. When ebef7e5049 (Documentation: simplify How Merge Works, 2010-01-23) tried to simplify the description, the list of "these things happen" were removed/rewritten, and yet instructions on how to reset are left behind, still referring to 2. and 3. We probably want a separate patch for Documentation/git-merge.adoc to rectify this 16 year old mistake.

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

Thanks for the review, I'm especially excited about the idea to remove zdiff3. >> Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com> >> Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com> >> Reviewed-by: Patrick Steinhardt <ps@pks.im> >> Signed-off-by: Julia Evans <julia@jvns.ca> > > We want a sign-off by the coauthor, too. Will do. >> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc >> new file mode 100644 >> index 0000000000..5b0ba1a1de >> --- /dev/null >> +++ b/Documentation/gitmergeconflicts.adoc >> @@ -0,0 +1,333 @@ >> +gitmergeconflicts(7) >> +==================== >> + >> +NAME >> +---- >> +gitmergeconflicts - 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 >> +the same merge algorithm, and the process for resolving a merge conflict >> +is always very similar. > > Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order > to limit ourselves to most common ways to help new people by keeping > the description to the absolute minimum? It's deliberate, we talked about that a bit in the discussion of the v1. Can add a note in the commit message. > In any case, the first paragraph clearly stating that conflicts > happen with operations other than 'merge' is a very welcome change. > On this list, we often say "mergy operations can cause conflicts", > with the understanding that readers know what mergy operations are > and "conflicts" alone can convey the state you call "merge > conflicts" in this document. But in a document for end-users, using > a longer term "merge conflicts" instead of "conflicts" and avoiding > "mergy operations" like you did above may be a better direction to > go. > >> +The most common ways to handle a merge conflict are: > > A natural paraphrase of the above is "A merge conflict is typically > handled by these ways", but I thought the current readers are > puzzled by "typically your side" that does not say when is typical. > >> +* 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. > > Both are good options and I do not think of a middle way. Perhaps > we do not have to say that these are "the most common" and instead > say "You handle a merge conflict by doing either of these two"? I agree the "the most common" is kind of weaselly and I'd like to be more clear. The reason I wrote "typically" is that during a rebase, there's an extra "skip" option, so it's not strictly true to say that there are just two options. Not sure if there's another option I'm not thinking of other than the "skip" in rebase. > Saying "return your branch to" is a bit misleading for two reasons. > Conflicts presented to the users are primarily visible in their > working tree files and the index. A single commit operations like > 'merge', 'pull', and 'revert' does not touch your branch if they hit > a conflict, and 'rebase' works on a detached HEAD, and stops without > touching your branch when it sees a conflict. > > If I were writing this, with the goal of avoiding the issues the > current text has you listed in the proposed log message, I would > probably say something like this: > > * Or give up and return to the original state with ... That's reasonable, I think "return to the original state" would be fine. Will look at this. > >> +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 >> +the same file, then it can easily combine them since there's no overlap. > > Many of the operations, even "git merge", is not about merging "two > commits" together, but I do not think of a good way to explain it, > so I accept that phrasing as a helpful white lie. I mention this > because somebody else may be able to come up with a better phrasing > that I (or authors of this iteration) couldn't think of. > >> +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 marks them as conflicted, puts both >> + sides' edits in the file, and leaves <<markers, merge conflict markers>> >> + that you need to resolve. > > By the way, I think we should briefly mention what sematnic merge > conflicts are, and that Git does not detect them and that this > manual page does not tell readers how to deal with them. > > Note that non-overlapping changes from two sides may leave the > result in an inconsistent state. With the edit to lines 1-5, > one side may have changed the name of a function, while with the > edit to lines 20-25, the other side may have added a new call to > the function by its original name. This type of inconsistencies > are called semantic conflicts, Git has no way knowing that a > merge introduced semantic conflicts, and ends up producing a > broken result without merge conflicts. This document does not > cover what to do with semantic conflicts. > > That is overly long, but perhaps you can condense it down to the > essense and shrink down to 1/3 of the size. I was thinking about that too. Maybe we can briefly mention that git's merges are not guaranteed to produce working code even when they succeed and point to an example further down the page. Added to my list of things to work on. >> +[[markers]] >> +MERGE CONFLICT MARKERS >> +---------------------- >> + >> +When there's a merge conflict, Git will update the conflicted file >> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`. > > I notice that when you introduce `diff3` below, you silently add > `|||||||` to the mix without explaining what it is. > > `|||||||` may also be used as merge conflict markers (explained > later). > > or something along the line here may help. Or explain what it is in > `diff3` section. Either would work. Adding without explanation > would not. I think explaining it in the diff3 section makes sense, will do. >> +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 >> + "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. > > If we said "one side wanted to have 'apple, cherry, mango, orange', > while the other side wanted 'apply, banana, mango, orange', in the > FRUITS array", would it help the understanding? Or is it too > obvious? I think it could make sense to add something here yes. Added to my list. >> +[[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", >> +] >> +---- > > It would make your readers puzzled why the example is subtly > different from the earlier one that showed "mango" as not touched by > either side. I see this lays the groundwork for later demonstration > of `diff3`, so having both sides explicitly want "mango" is a good > example. Perhaps update the first example to be the same as this > one, which would reduce the mental burden by readers? I very much agree it's important for the examples to match, will work on that. It's a bit tricky with diff3 like you say. >> +[[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. >> + >> +* You can set the configuration option `merge.conflictstyle=diff3`. >> + See <<diff3,DIFF3 AND ZDIFF3>> below for more. > > These are called 'configuration variables' throughout the manual > pages. Be consistent and replace "configuration option" with > "configuration variable", perhaps? They seem to be both used interchangeably already: ``` $ grep 'configuration variable' *.adoc | wc -l 256 $ grep 'configuration option' *.adoc | wc -l 46 ``` `git-config.adoc` uses the term "configuration option" 2 times and "configuration variable" once. Is there supposed to be some difference between these terms? As far as I can tell from brief history spelunking Git has used those terms interchangeably for a long time. AFAIK "configuration option" is the term more often used outside Git. >> +* `git log --merge -p <filename>` will list all commits which >> + caused the merge conflict for `<filename>`, and the diff >> + of how they changed the file. > > Maybe worth mentioning that `--left-right` often helps when you are > not super familiar with the histories being merged. I don't understand what this does or what it would be useful for so it's not possible for me to explain it :). From my perspective "ours" and "theirs" are already confusing enough and introducing "left" and "right" seems like a lot. Is "left" the same as "ours"? >> +* Look at the original files. `git show :1:filename` shows the >> + common ancestor, `git show :2:filename` shows the "ours" >> + version, and `git show :3:filename` shows the "theirs" >> + version. > > Maybe it will help to say we will explain "ours" and "theirs" later > in this document. Plausible, added to my todo list to look at, thanks. >> +* Use `git diff AUTO_MERGE` to show what changes you've made so far to >> + resolve the conflicts. > > Does a "See below" here help readers who haven't learned what > AUTO_MERGE is? If you can describe what AUTO_MERGE records (in > other words, what you are comparing your progress against) in a > sentence of two here, that would alleviate the need to assure them > that we have more in-depth coverage on this topic elsewhere. I think this is okay the way it is. >> +[[git_status]] >> +EXAMPLE: GIT STATUS OUTPUT >> +-------------------------- >> + >> +When you're in a merge conflict, you can find out what commands to run >> +to handle the conflict by running `git status`. >> + >> +For example, this `git status` output tells you that: >> + >> +* `git rebase --abort` will safely bring your branch back to its >> + original state >> +* you should run `git rebase --continue` when you're done resolving all >> + the conflicts >> +* there's one file left with conflicts in it: `fruits.py` > > There may be users, after seeing the last point, left puzzled why > fruits.py is still listed after they edited the file like instructed > in an earlier example but haven't marked the resolution. > > `fruits.py` is not marked as its conflicts resolved yet. > > or something? Thanks, agreed that "there's one file left with conflicts in it: `fruits.py`" isn't precise enough. Will make it more accurate. >> +---- >> +$ git status >> +You are currently rebasing branch 'main' on '58a9fcc'. >> + (fix conflicts and then run "git rebase --continue") >> + (use "git rebase --skip" to skip this patch) >> + (use "git rebase --abort" to check out the original branch) >> + >> +Unmerged paths: >> + (use "git restore --staged <file>..." to unstage) >> + (use "git add <file>..." to mark resolution) >> + both modified: fruits.py >> +---- > > The approach to give explanations first and then an example the > explanation explains next is refreshing to me. As long as the > explanations are short enough, this may work better than the usual > order to say "you'd see something like this. let us explain ...". Glad to hear it! >> +[[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. > > I think most on the list considers `zdiff3` a failed experiment that > reduces usefulness of `diff3`. Do we want to recommend it? I'd be extremely happy to remove this if the list doesn't think zdiff3 is useful. When I was writing this I was confused by zdiff3 and thought diff3 made a lot more sense. Maybe we could add a note like this somewhere? NOTE: zdiff3 was an experimental alternative to diff3 that makes the merge conflict shorter by introducing more ambiguity. It's still there for backwards compatibility but we don't recommend it. > By the way, is it just me who finds those "Here's", "there's" > contractions disturbing in an official manual? I've seen many of > them while reviewing this to be annoyed enough and had to blurt it > out X-<. I find "here is" and "there is" to be distracting and overly formal, different people are different I guess :) >> +"Ours" and "theirs" are both commits: "ours" is the current >> +`HEAD` commit, and "theirs" is the other side being merged. > > Now, "commits" is again a white lie. The story becomes more > complicated when we talk about cherry-pick and revert, but if we > primarily stick to what happens in 'merge' (which is what I've seen > so far in this document), then it shouldn't add any extra difficulty > to understand by saying "ours and theirs are history of changes > leading to the two commits since they diverged from the original" to > add clarity. > >> +The first part of a merge conflict (between `<<<<<<<` and `=======`) is >> +from the "ours" side, and the second part (between `=======` and >> +`>>>>>>>`) is from the "theirs" side. >> + >> +---- >> +FRUITS = [ >> + "apple", >> +<<<<<<< HEAD >> + "cherry", <- ours >> +======= >> + "banana", <- theirs >> +>>>>>>> add-fruit >> + "mango", >> + "orange", >> +] >> +---- >> + >> +During a rebase, it can seem "upside down" because the "ours" commit is >> +from the branch you're rebasing on (for instance `main` in `git rebase >> +main`). >> + >> +These terms in Git all mean the same thing when dealing with a merge >> +conflict: >> + >> +* "common ancestor" and "base". The files from this commit are "in stage 1". >> +* "ours", "us", and `HEAD`. The files from this commit are "in stage 2". >> +* "theirs", "them". The files from this commit are "in stage 3". >> + >> +If you're confused about what something like "deleted by us" means, it's >> +often easiest to use some of the tools from >> +<<tools,TOOLS FOR HANDLING MERGE CONFLICTS>> above to get more context. >> +Finding the commit that deleted the file and seeing why is usually more >> +helpful than trying to abstractly reason through what "us" means. >> + >> +[[automerge]] >> +EXAMPLE OF USING `AUTO_MERGE` >> +----------------------------- >> + >> +`git diff AUTO_MERGE` will show what changes you've made so far to >> +resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a >> +merge. It contains the result of running the merge algorithm. > > The first sentence gave me "Huh? You haven't explained what > AUTO_MERGE is yet". It may be just me, but I would have expected > presentation order to be more like: > > When merge conflicts happen, the result of merge algorithm, > together with conflict markers, is recorded in AUTO_MERGE. As > you resolve conflicts, you can compare your working tree files > against it with `git diff AUTO_MERGE` to see your progress. Can take a look but I don't think it makes a big difference. >> +For example, if we resolved the conflict by adding both "banana" and >> +"cherry" in order, the diff would look like this: >> + >> +---- >> + FRUITS = [ >> + "apple", >> +-<<<<<<< HEAD >> +- "cherry", >> +-======= >> + "banana", >> +->>>>>>> add-fruit >> ++ "cherry", >> + "mango", >> + "orange", >> + ] >> +---- > > Thanks. > > > I was puzzled by this > >> - In "The only clean-ups you need are to reset the index file to the >> `HEAD` commit to reverse 2. and to clean up working tree changes made >> by 2. and 3.", it's not clear to users what "2" and "3" are supposed >> to mean > > and did some digging. > > The text comes from ffb1a4bed5 (Documentation: Describe merge > operation a bit better., 2005-11-28) that had "When there are > conflicts, these things happen. 1. HEAD does not move, 2. Cleanly > merged paths are updated in the index 3. Conflicts are recorded in > higher stage index entries and working tree files show conflict > markers, 4. No other changes are done" well before the mysterious > reference to 2. and 3. > > When ebef7e5049 (Documentation: simplify How Merge Works, > 2010-01-23) tried to simplify the description, the list of "these > things happen" were removed/rewritten, and yet instructions on how > to reset are left behind, still referring to 2. and 3. > > We probably want a separate patch for Documentation/git-merge.adoc > to rectify this 16 year old mistake. Thanks for investigating!

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

"Julia Evans" <julia@jvns.ca> writes: >>> +* 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. >> >> Both are good options and I do not think of a middle way. Perhaps >> we do not have to say that these are "the most common" and instead >> say "You handle a merge conflict by doing either of these two"? > > I agree the "the most common" is kind of weaselly and I'd like to be more clear. > The reason I wrote "typically" is that during a rebase, there's an extra > "skip" option, so it's not strictly true to say that there are just two options. > Not sure if there's another option I'm not thinking of other than the > "skip" in rebase. I do not think anything like "rebase --skip" in a multi-step integration is what this document covers particularly well to begin with. Taking each conflicted step individually, with "skip", you are stopping the operation without resolving the conflict. Perhaps make it clear that in the above you are talking about what to do with each individual opportunity to give back conflict resolution to the command? If you describe these two choices in the context of multi-step operation, each "we stopped due to conflict and gave control back to you" opportunity gives you these choices: * Give up, pretend this step did not exist, and continue. * Resolve the conflict, record it, and continue. In addition, you have "--abort" to give up the whole thing. And a single step operation like "git merge" is a degenerated case of the above. "and continue" part does not exist. > I was thinking about that too. Maybe we can briefly mention that git's > merges are not guaranteed to produce working code even when they > succeed and point to an example further down the page. > Added to my list of things to work on. It's not limited to "GIt's merges" but applies in general. >>> +[[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. >>> + >>> +* You can set the configuration option `merge.conflictstyle=diff3`. >>> + See <<diff3,DIFF3 AND ZDIFF3>> below for more. >> >> These are called 'configuration variables' throughout the manual >> pages. Be consistent and replace "configuration option" with >> "configuration variable", perhaps? > > They seem to be both used interchangeably already: > > ``` > $ grep 'configuration variable' *.adoc | wc -l > 256 > $ grep 'configuration option' *.adoc | wc -l > 46 > ``` Do not make it worse. The latter were mostly added people like you who responds like the above; aim to be more consistent instead. >>> +* `git log --merge -p <filename>` will list all commits which >>> + caused the merge conflict for `<filename>`, and the diff >>> + of how they changed the file. >> >> Maybe worth mentioning that `--left-right` often helps when you are >> not super familiar with the histories being merged. > > I don't understand what this does or what it would be useful for so > it's not possible for me to explain it :). From my perspective > "ours" and "theirs" are already confusing enough and introducing > "left" and "right" seems like a lot. Is "left" the same as "ours"? If you do not understand what it does, perhaps try it out? "git log -p --merge" is to break down the ours/theirs into individual steps when changes on these sides were brought in in multiple steps. It shows individual changes per commit, but if you are not super familiar with these histories being merged, it is not obvious which commit came from which side. And --left-right option is a way to help you tell which one came from which. >>> +* Use `git diff AUTO_MERGE` to show what changes you've made so far to >>> + resolve the conflicts. >> >> Does a "See below" here help readers who haven't learned what >> AUTO_MERGE is? If you can describe what AUTO_MERGE records (in >> other words, what you are comparing your progress against) in a >> sentence of two here, that would alleviate the need to assure them >> that we have more in-depth coverage on this topic elsewhere. > > I think this is okay the way it is. Is it because, unlike --left-right, you understand what it does? Not everybody shares what you know, you know ;-) * AUTO_MERGE records the initial merge result with conflict markers. `git diff AUTO_MERGE` can be used to show how much progress you made to resolve these conflicts. perhaps. > Maybe we could add a note like this somewhere? > > NOTE: zdiff3 was an experimental alternative to diff3 that makes > the merge conflict shorter by introducing more ambiguity. > It's still there for backwards compatibility but we don't recommend it. Drop "experimental" and I am 100% behind that statement ;-). >> By the way, is it just me who finds those "Here's", "there's" >> contractions disturbing in an official manual? I've seen many of >> them while reviewing this to be annoyed enough and had to blurt it >> out X-<. > > I find "here is" and "there is" to be distracting and overly formal, > different people are different I guess :) I would prefer to be consistent in a single documentation set, though. >> The text comes from ffb1a4bed5 (Documentation: Describe merge >> operation a bit better., 2005-11-28) that had "When there are >> conflicts, these things happen. 1. HEAD does not move, 2. Cleanly >> merged paths are updated in the index 3. Conflicts are recorded in >> higher stage index entries and working tree files show conflict >> markers, 4. No other changes are done" well before the mysterious >> reference to 2. and 3. >> >> When ebef7e5049 (Documentation: simplify How Merge Works, >> 2010-01-23) tried to simplify the description, the list of "these >> things happen" were removed/rewritten, and yet instructions on how >> to reset are left behind, still referring to 2. and 3. >> >> We probably want a separate patch for Documentation/git-merge.adoc >> to rectify this 16 year old mistake. > > Thanks for investigating! Heh, you already did the separate patch, which is [2/6], which I am happy with.

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

"Julia Evans" <julia@jvns.ca> writes: Comments on a few more points. >> Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order >> to limit ourselves to most common ways to help new people by keeping >> the description to the absolute minimum? > > It's deliberate, we talked about that a bit in the discussion of the v1. > Can add a note in the commit message. Being a part of _the_ technical manual on Git, I would like to see us aim for completeness, and where we don't leave a note that the description is not complete. In this case, between Merge conflicts can happen during a `git merge`, `git rebase`, `git cherry-pick`, `git pull`, `git am -3`, `git checkout -m`, `git stash pop`, or `git revert`. that aims for completeness and Merge conflicts can happen during a `git merge`, `git rebase`, `git cherry-pick`, `git pull`, or `git revert`, and other operations. that admits the list is not complete, I have slight preference to the first one. >> By the way, is it just me who finds those "Here's", "there's" >> contractions disturbing in an official manual? I've seen many of >> them while reviewing this to be annoyed enough and had to blurt it >> out X-<. > > I find "here is" and "there is" to be distracting and overly formal, > different people are different I guess :) But I wouldn't want you to be "different" here. This is not your diary or personal note. This being a part of the technical manual, I would prefer to see the same formalness applied everywhere.

gitgitgadget · 2026-10-09T19:00:53Z

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


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> > > All of the info about merge conflicts has been moved to the new guide In the body text end the sentence with a full stop. And I just went though the "new guide" with fine toothed comb, I am very much qualified to judge if the above claim is correct. Let's see. > @@ -231,127 +232,6 @@ git merge v1.2.3^0 > git merge --ff-only v1.2.3 > ---- > > -HOW CONFLICTS ARE PRESENTED > ---------------------------- > - > -During a merge, the working tree files are updated to reflect the result > -of the merge. 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. OK. We said working tree files are updated. We made a weak reference to "common ancestor" but with my suggested updates I think we sufficiently cover this. "Git cannot ... and asks you ..." had a nice nuance that we may not have captured in the new document (we stop at "will not try to guess" and say "asks you to pick" in a seaprate paragraph, which feels a bit detached than the original here [***]). > -By default, Git uses the same style as the one used by the "merge" program > -from the RCS suite to present such a conflicted hunk, like this: > - > ------------- > -Here are lines that are either unchanged from the common > -ancestor, or cleanly resolved because only one side changed, > -or cleanly resolved because both sides changed the same way. > -<<<<<<< yours:sample.txt > -Conflict resolution is hard; > -let's go shopping. > -======= > -Git makes conflict resolution easy. > ->>>>>>> theirs:sample.txt > -And here is another line that is cleanly resolved or unmodified. > ------------- > - > -The area where a pair of conflicting changes happened is marked with markers > -+<<<<<<<+, `=======`, and +>>>>>>>+. The part before the `=======` > -is typically your side, and the part afterwards is typically their side. > - > -The default format does not show what the original said in the conflicting > -area. You cannot tell how many lines are deleted and replaced with > -Barbie's remark on your side. The only thing you can tell is that your > -side wants to say it is hard and you'd prefer to go shopping, while the > -other side wants to claim it is easy. We covered all of the above, except for the reference to RCS which we explicitly wanted to lose. Good. > -An alternative style can be used by setting the `merge.conflictStyle` > ... > -In addition to the +<<<<<<<+, `=======`, and +>>>>>>>+ markers, it uses > -another +|||||||+ marker that is followed by the original text. This is what we were missing in the new guide, which I tried to rectify without looking at this exact text. In any shape it should be preserved somehow [***]. > - You can > -tell that the original just stated a fact, and your side simply gave in to > -that statement and gave up, while the other side tried to have a more > -positive attitude. You can sometimes come up with a better resolution by > -viewing the original. We covered this with "fruits from both sides" example, and I think the explanation there is shorter and simpler to understand. > -HOW TO RESOLVE CONFLICTS > ------------------------- > - > -After seeing a conflict, you can do two things: > - > - * Decide not to merge. The only clean-ups you need are to reset > - the index file to the `HEAD` commit to reverse 2. and to clean > - up working tree changes made by 2. and 3.; `git merge --abort` > - can be used for this. > - > - * Resolve the conflicts. Git will mark the conflicts in > - the working tree. Edit the files into shape and > - `git add` them to the index. Use `git commit` or > - `git merge --continue` to seal the deal. The latter command > - checks whether there is a (interrupted) merge in progress > - before calling `git commit`. The new text tried to have a wiggle room with "most common", but nothing is lost from the above if we tweak it with my suggested "there are only two" [***]. > -You can work through the conflict with a number of tools: > - > - * Use a mergetool. `git mergetool` to launch a graphical > - mergetool which will work through the merge with you. > - > - * Look at the diffs. `git diff` will show a three-way diff, > - highlighting changes from both the `HEAD` and `MERGE_HEAD` > - versions. `git diff AUTO_MERGE` will show what changes you've > - made so far to resolve textual conflicts. > - > - * 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. > - > - * Look at the originals. `git show :1:filename` shows the > - common ancestor, `git show :2:filename` shows the `HEAD` > - version, and `git show :3:filename` shows the `MERGE_HEAD` > - version. We covered this in "Tools for handling" section. This version groups AUTO_MERGE together with other tools, which may have its advantages and disadvantages. The latter two bullet points in the above list is about static view, so is three-way O A B diff. Use of mergetool and 'diff AUTO_MERGE" are more dynamic "how far have you come" view. So separating the "git diff" that shows three-way comparison and "git diff AUTO_MERGE" in the new document sounds like an improvement (even though 'mergetool' blurs the boundary between "how the conflict looked like" and "what your eventual conflict you are working toward may look like", though [***]). Overall, I fully agree with these removals. We may want to take a few points (marked with [***]) we learned during this review back to the new document from here, though. Thanks.

gitgitgadget · 2026-10-09T19:01:16Z

@@ -46,10 +46,7 @@ If there is a merge conflict during this process, `git rebase` will stop at the
 first problematic commit and leave conflict markers. If this happens, you can do


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 some of the detail about how to handle a merge conflict, since > it's explained in detail in the new guide, and there probably isn't > enough detail anyway. > > Leave the steps since rebase is special and has a `--skip` option which > the other commands which cause merge conflicts don't have. > > Signed-off-by: Julia Evans <julia@jvns.ca> > --- > Documentation/git-rebase.adoc | 13 +++++++++---- > 1 file changed, 9 insertions(+), 4 deletions(-) Great. There is nothing I would miss from these removed lines. All are already described better in the new document, with or without suggestions I made during reviews of [1/6] and [2/6].

gitgitgadget · 2026-10-09T19:01:42Z

@@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory.
 See "Reset, restore and revert" in linkgit:git[1] for the differences


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> > > Signed-off-by: Julia Evans <julia@jvns.ca> > --- > Documentation/git-revert.adoc | 5 +++++ > 1 file changed, 5 insertions(+) > > diff --git a/Documentation/git-revert.adoc b/Documentation/git-revert.adoc > index ffba365e63..1edf98b9aa 100644 > --- a/Documentation/git-revert.adoc > +++ b/Documentation/git-revert.adoc > @@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory. > See "Reset, restore and revert" in linkgit:git[1] for the differences > between the three commands. > > +If there have been new commits since the reverted commit, there may > +be a merge conflict. See linkgit:gitmergeconflicts[7] > +(or `git help mergeconflicts`) for a guide to handling merge conflicts. > + This is a strange thing to say. Is it worth special casing the revert of the tip commit that much? "Reverting a commit may resolt in a merge conflict" should be sufficient, I would think. > OPTIONS > ------- > <commit>...:: > @@ -162,6 +166,7 @@ include::config/revert.adoc[] > SEE ALSO > -------- > linkgit:git-cherry-pick[1] > +linkgit:gitmergeconflicts[7] > > GIT > ---

gitgitgadget · 2026-10-09T19:02:12Z

@@ -19,8 +19,11 @@ Given one or more existing commits, apply the change each one
 introduces, recording a new commit for each.  This requires your


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

"Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes: > -When it is not obvious how to apply a change, the following > -happens: > +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. "Obvious to whom" was the first thing that came to my mind, even though the blame largely lies on the original. Can't we get rid of the above pragraph altogether, and "See new one" at the end where you replaced "See git-merge" reference below? > +When a merge conflict happens: > > 1. The current branch and `HEAD` pointer stay at the last commit > successfully made. > @@ -36,9 +39,6 @@ happens: > conflict markers `<<<<<<<` and `>>>>>>>`. > 5. No other modifications are made. > > -See linkgit:git-merge[1] for some hints on resolving such > -conflicts. > - > OPTIONS > ------- > <commit>...:: > @@ -259,6 +259,7 @@ $ git cherry-pick -Xpatience topic^ <4> > SEE ALSO > -------- > linkgit:git-revert[1] > +linkgit:gitmergeconflicts[7] > > GIT > ---

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

On Fri, Oct 9, 2026, at 2:26 PM, Junio C Hamano wrote: > "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes: > >> -When it is not obvious how to apply a change, the following >> -happens: >> +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. > > "Obvious to whom" was the first thing that came to my mind, even > though the blame largely lies on the original. Can't we get rid of > the above pragraph altogether, and "See new one" at the end where > you replaced "See git-merge" reference below? Sounds good to me. Same for the language around revert. >> +When a merge conflict happens: >> >> 1. The current branch and `HEAD` pointer stay at the last commit >> successfully made. >> @@ -36,9 +39,6 @@ happens: >> conflict markers `<<<<<<<` and `>>>>>>>`. >> 5. No other modifications are made. >> >> -See linkgit:git-merge[1] for some hints on resolving such >> -conflicts. >> - >> OPTIONS >> ------- >> <commit>...:: >> @@ -259,6 +259,7 @@ $ git cherry-pick -Xpatience topic^ <4> >> SEE ALSO >> -------- >> linkgit:git-revert[1] >> +linkgit:gitmergeconflicts[7] >> >> GIT >> ---

gitgitgadget · 2026-10-09T19:02:43Z

@@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour.



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> > > Signed-off-by: Julia Evans <julia@jvns.ca> > --- > Documentation/git-pull.adoc | 3 ++- > 1 file changed, 2 insertions(+), 1 deletion(-) > > diff --git a/Documentation/git-pull.adoc b/Documentation/git-pull.adoc > index 88f4fd3926..73f6d460bb 100644 > --- a/Documentation/git-pull.adoc > +++ b/Documentation/git-pull.adoc > @@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour. > > If there's a merge conflict during the merge or rebase that you don't > want to handle, you can safely abort it with `git merge --abort` or > -`git rebase --abort`. > +`git rebase --abort`. See linkgit:gitmergeconflicts[7] > +(or `git help mergeconflicts`) for a guide to handling merge conflicts. > > OPTIONS > ------- Very good.

gitgitgadget · 2026-10-09T19:03:10Z

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

I've sent detailed reviews on #1 and commented on others.

You add my Reviewed-by: on [2/6], [3/6], and [6/6] if your new
iteration uses them as-is.  My suggestions to [4/6] and [5/6] are
both straight-forward, so if you choose to take them literally,
you can add my Reviewed-by: on them, too.

Thanks.

gitgitgadget · 2026-10-09T23:08:17Z

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

> Le 9 oct. 2026 à 11:41, Junio C Hamano <gitster@pobox.com> a écrit :
> 
> > "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 
> For example, you added Ben and Patrick to the trailer of patch #1.
> 
>> Range-diff vs v1:
>> 
>> 1:  ad4853dc36 ! 1:  ab0344f947 [doc] Add new gitmergeconflicts man page
>>     @@ Metadata
>>      Author: Julia Evans <julia@jvns.ca>
>> 
>>       ## Commit message ##
>>     -    [doc] Add new gitmergeconflicts man page
>>     +    doc: add new gitmergeconflicts man page
>> ...
>>          Co-Authored-By: Marie Claire LeBlanc Flanagan <hello@marieflanagan.com>
>>     +    Reviewed-by: D. Ben Knoble <ben.knoble+github@gmail.com>
>>     +    Reviewed-by: Patrick Steinhardt <ps@pks.im>
>>          Signed-off-by: Julia Evans <julia@jvns.ca>

PS I think I just use my non-suffixed email on this project; 
see our .mailmap :)

gitgitgadget · 2026-10-10T02:17:46Z

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

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

Expecting a reroll.
cf. <xmqqse2evq2k.fsf@gitster.g>
cf. <2a721921-2865-4cc4-8cd2-01eae74f27a5@app.fastmail.com>
source: <pull.2237.v2.git.1791547213.gitgitgadget@gmail.com>

jvns changed the title ~~Merge conflicts~~ [doc] Add new page on merge conflicts Sep 23, 2026

jvns force-pushed the merge-conflicts branch 3 times, most recently from 9058e0a to 420858b Compare September 23, 2026 15:44

jvns force-pushed the merge-conflicts branch from 31c5eec to 96ec49e Compare September 23, 2026 16:59

jvns force-pushed the merge-conflicts branch from 96ec49e to 4505fdc Compare September 24, 2026 14:26

gitgitgadget Bot added the seen label Sep 24, 2026

gitgitgadget Bot reviewed Sep 24, 2026

View reviewed changes

gitgitgadget Bot reviewed Sep 25, 2026

View reviewed changes

jvns force-pushed the merge-conflicts branch from c9e34b1 to 462152c Compare October 7, 2026 13:46

jvns force-pushed the merge-conflicts branch from 462152c to 5aa2c96 Compare October 7, 2026 13:49

jvns and others added 6 commits October 7, 2026 15:38

doc: git-merge: link to new merge conflicts guide

d5241eb

All of the info about merge conflicts has been moved to the new guide Signed-off-by: Julia Evans <julia@jvns.ca>

doc: git-revert: link to new merge conflicts guide

cfa0a82

Signed-off-by: Julia Evans <julia@jvns.ca>

doc: git-cherry-pick: link to new merge conflicts guide

62b70e9

Remove the discussion of merge conflicts and replace it with a link to the guide. Signed-off-by: Julia Evans <julia@jvns.ca>

doc: git-pull: link to new merge conflicts guide

ac77db6

Signed-off-by: Julia Evans <julia@jvns.ca>

jvns force-pushed the merge-conflicts branch from 5aa2c96 to ac77db6 Compare October 7, 2026 19:38

gitgitgadget Bot reviewed Oct 7, 2026

View reviewed changes

gitgitgadget Bot reviewed Oct 9, 2026

View reviewed changes

		@@ -58,6 +58,7 @@ MAN7_TXT += gitdiffcore.adoc
		MAN7_TXT += giteveryday.adoc

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

		@@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace
		/t/oid-info/* text eol=lf

		@@ -46,10 +46,7 @@ If there is a merge conflict during this process, `git rebase` will stop at the
		first problematic commit and leave conflict markers. If this happens, you can do

		@@ -31,6 +31,10 @@ both will discard uncommitted changes in your working directory.
		See "Reset, restore and revert" in linkgit:git[1] for the differences

		@@ -19,8 +19,11 @@ Given one or more existing commits, apply the change each one
		introduces, recording a new commit for each. This requires your

		@@ -38,7 +38,8 @@ or `pull.ff` with your preferred behaviour.

Conversation

jvns commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gitgitgadget Bot commented Sep 23, 2026

Uh oh!

gitgitgadget Bot commented Sep 23, 2026

Uh oh!

gitgitgadget Bot commented Sep 23, 2026

Uh oh!

gitgitgadget Bot commented Sep 23, 2026

Uh oh!

gitgitgadget Bot commented Sep 23, 2026

Uh oh!

gitgitgadget Bot commented Sep 23, 2026

Uh oh!

jvns commented Sep 23, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

dscho commented Sep 23, 2026

Uh oh!

jvns commented Sep 23, 2026

Uh oh!

dscho commented Sep 23, 2026

Uh oh!

jvns commented Sep 23, 2026

Uh oh!

jvns commented Sep 23, 2026

Uh oh!

gitgitgadget Bot commented Sep 23, 2026

Uh oh!

jvns commented Sep 24, 2026

Uh oh!

gitgitgadget Bot commented Sep 24, 2026

Uh oh!

gitgitgadget Bot commented Sep 24, 2026

Uh oh!

gitgitgadget Bot Sep 24, 2026

Choose a reason for hiding this comment

Uh oh!

gitgitgadget Bot Sep 24, 2026

Choose a reason for hiding this comment

Uh oh!

gitgitgadget Bot commented Sep 25, 2026

Uh oh!

gitgitgadget Bot commented Sep 25, 2026

Uh oh!

gitgitgadget Bot commented Sep 25, 2026

Uh oh!

gitgitgadget Bot commented Sep 25, 2026

Uh oh!

gitgitgadget Bot commented Sep 25, 2026

Uh oh!

gitgitgadget Bot Sep 25, 2026

Choose a reason for hiding this comment

Uh oh!

gitgitgadget Bot Sep 25, 2026

Choose a reason for hiding this comment

Uh oh!

gitgitgadget Bot Sep 25, 2026

Choose a reason for hiding this comment

Uh oh!

gitgitgadget Bot Sep 25, 2026

Choose a reason for hiding this comment

Uh oh!

gitgitgadget Bot Sep 25, 2026

Choose a reason for hiding this comment

Uh oh!

gitgitgadget Bot Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

gitgitgadget Bot Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

gitgitgadget Bot Oct 2, 2026

Choose a reason for hiding this comment

Uh oh!

gitgitgadget Bot Oct 3, 2026

Choose a reason for hiding this comment

Uh oh!

jvns commented Sep 23, 2026 •

edited

Loading

jvns commented Sep 23, 2026 •

edited

Loading