Re: [PATCH 1/7] [doc] Add new gitmergeconflicts man page

From: Julia Evans <julia@jvns.ca>
Date: Sep 30, 2026, 19:53 UTC
Message-ID: <5ba2088c-4919-465f-8892-4ed0685f81ea@app.fastmail.com>
In-Reply-To: <ar0MVRV5X8zgZfLy@pks.im>

Show 5 quoted lines

>> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
>> +cherry-pick`, `git pull`, or `git revert`. All of those commands use
>
> Should all of these be using linkgit:, like for example in
> linkgit:git-merge[1]?

Makes sense to me, will change.

Show 16 quoted lines

>> +The most common ways to handle a merge conflict are:
>> +
>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
>> +  below for details)
>> +* Or stop the operation and return your branch to its original state
>> +  with the appropriate `--abort` command, for example `git merge --abort`
>> +  or `git rebase --abort`. See <<git_status,EXAMPLE: GIT STATUS OUTPUT>> below
>> +  for how to find the command to run.
>
> I wonder whether the explanation should be expanded a bit to briefly
> explain how Git performs a 3-way merge in the first place. I feel like
> it's quite important to understand what the three different sides of the
> merge are to make sense of it.
>
> But I may be too far detached from the "normal" user, so this may only
> cause more confusion for our users.

I think it would cause more confusion. I did some experiments in explaining merge conflicts using the concept of 3-way merge a couple of years ago and it didn't go well.

My experience was that what users they found the most useful was learning about the tools Git offers (like `git diff --check` and `diff3`), so that's why this document focuses on tools and formatting much more than concepts.

I think it would be cool to find a way to explain how 3-way merge works at in this document in some later iteration though, maybe at the end. Definitely some folks would find it interesting. I didn't understand 3-way merge myself until a couple of years ago and it was fun for me to learn, but it didn't really help me use Git effectively.

(this is quickly becoming a bit of a novel, but it's often very counterintuitive how some facts that seem "fundamental" about how Git works actually turn out to not be very important to understand in practice to use it effectively. It's something I find tough to talk about on this mailing list because it's something I've only been able to learn empirically)

Show 10 quoted lines

>> +[[markers]]
>> +MERGE CONFLICT MARKERS
>> +----------------------
>> +
>> +Merge conflicts happen when both of the sides being merged edit the same
>> +area of a file. When this happens, Git will update the conflicted file
>
> I wonder whether we want to use "hunk" instead of "area". It's jargon
> again, but I have never heard anybody speak about an "area" before
> myself.

Ah thanks, I think I took "area" from the `git-merge` man page.

I looked up how I explained this previously and I used "lines of code", which I think communicates the same meaning without the jargon. I'll try that instead.

>> +Note: During a `git merge`, `git commit` and `git merge --continue` do
>> +the the same thing.
>
> s/the the/the/

Will fix.

Show 18 quoted lines

>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
>> +For example, here's a merge conflict where both sides edited a list of
>> +fruits in different ways:
>> +
>> +----
>> +FRUITS = [
>> +    "apple",
>> +<<<<<<< HEAD
>> +    "cherry",
>> +=======
>> +    "banana",
>> +>>>>>>> add-fruit
> Hide quoted text
>
> A bit of a tangent, but sometimes I wonder whether we should make the
> respective commits a bit easier to access. For example, we could put the
> equivalent of `git rev-parse --reference <commit>` here for each of the
> sides.

Personally I'm not sure if the commit ID would do much for me, but I feel like it would help me if it were possible to include the commit message.

> I tend to forget that by default, we only render ours/theirs in the
> conflict. I always feel like that makes it way harder to resolve
> conflicts as you don't have the context of what the code looked like
> originally. So I have diff3 configured locally for ages.

Every time I show people diff3 someone tells me how happy they are to learn it :)

Show 7 quoted lines

>> +* There are many graphical "merge tools" for Git, which will normally
>> +  show you the different versions of the code side by side.
>> +  If you have a mergetool configured, `git mergetool` will launch it.
>> +  See also `merge.tool` in linkgit:git-config[1] for a list of
>> +  the mergetools Git supports.
>
> There's also `git merge-tool --tool-help` to list all available drivers.

Oh, cool! It's fun that it autodetects which ones you have installed on your system. I'll suggest that.

Show 36 quoted lines

>
> [snip]
>> +[[ours]]
>> +"OURS" AND "THEIRS"
>> +-------------------
>> +
>> +Git refers to the first part of a merge conflict (between `<<<<<<<`
>> +and `=======`) as "ours" and the second part (between `=======` and
>> +`>>>>>>>`) as "theirs".
>> +
>> +Normally, "ours" is the commit that was checked out before you started
>> +the merge, and "theirs" is the other commit.
>> +
>> +But when the merge conflict was caused by a `git rebase`, it's the
>> +opposite: "theirs" is the commit that was checked out before you started
>> +the merge. This is because under the hood, `git rebase main` checks out
>> +the `main` commit first before doing the merge operation.
>
> Hmm. This part is a bit confusing to me. "ours" is always the commit
> that's currently checked out, and "theirs" is always the one that is
> getting merged into the checked-out commit.
>
> How about a variant of the following instead?
>
>   In a conflict, the side between `<<<<<<<` and `=======` is "ours"
>   and the side between `=======` and `>>>>>>>` is "theirs". "Ours" is
>   always the side that `HEAD` points to while the merge happens; "theirs"
>   is the commit being merged into it.
>
>   For `git merge <other>`, `HEAD` is your current branch, so "ours" is
>   your branch and "theirs" is `<other>`.
>
>   For `git rebase <upstream>`, `HEAD` is first moved to `<upstream>` and
>   your commits are then replayed on top one at a time. So "ours" is the
>   already-rebased history starting at `<upstream>`, and "theirs" is the
>   commit from your original branch that is currently being replayed.

Thanks, your suggestion gives me some other ways to think about this.

I think I'll try to write something shorter that is unambiguous, instead of trying to use more words to make it feel more intuitive. I don't think I actually know anyone who feels it's easy to understand the way merge conflicts are presented, and more explanation may not help.

It might be more useful here to encourage (again) folks to use one of the many amazing tools available (in the "tools" section) to get more context.

Show 12 quoted lines

>> +These terms in Git all mean the same thing when dealing with a merge
>> +conflict:
>> +
>> +* "common ancestor", "base", and "stage 1"
>> +* "ours", "us", "stage 2", and `HEAD`
>> +* "theirs", "them", and "stage 3"
>
> I wouldn't say that "stage N" is equivalent to the respective other
> terms. These stages rather refer to the different versions of a specific
> file as recorded in the index, they do not indicate a specific commit.
> In contrast to that, all the other terms may also indicate a specific
> version of a file, but may also refer to the commits.

Thanks, will try to figure out how to make it more accurate. We could also refer to gitdatamodel if folks want to learn what the term "stage" means too.

Thanks for the review!
- Julia