Re: [PATCH 2/7] [doc] git-merge: link to new merge conflicts guide

From: Julia Evans <julia@jvns.ca>
Date: Oct 2, 2026, 17:01 UTC
Message-ID: <4e579181-e93a-4746-8c2d-b127cb0e053d@app.fastmail.com>
In-Reply-To: <2f71028f-d58e-400f-a02e-7a25c032d889@app.fastmail.com>

On Fri, Sep 25, 2026, at 12:59 PM, Julia Evans wrote:

Show 16 quoted lines

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

Show 8 quoted lines

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