Re: [PATCH 0/7] [doc] Add new page on merge conflicts

A big thank you for working on this.

On Thu, Sep 24, 2026 at 10:46 AM Julia Evans via GitGitGadget
[off-list ref] 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 (local)

 * 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