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

From: Patrick Steinhardt <ps@pks.im>
Date: Oct 1, 2026, 05:14 UTC
Message-ID: <ar3sGzEknG2_Un_E@pks.im>
In-Reply-To: <xmqqqzia8ohv.fsf@gitster.g>

On Wed, Sep 30, 2026 at 01:37:16PM -0700, Junio C Hamano wrote:

Show 31 quoted lines

> "Julia Evans" <julia@jvns.ca> writes:
> 
> >>> +to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.
> >>> +For example, here's a merge conflict where both sides edited a list of
> >>> +fruits in different ways:
> >>> +
> >>> +----
> >>> +FRUITS = [
> >>> +    "apple",
> >>> +<<<<<<< HEAD
> >>> +    "cherry",
> >>> +=======
> >>> +    "banana",
> >>> +>>>>>>> add-fruit
> >> Hide quoted text
> >>
> >> A bit of a tangent, but sometimes I wonder whether we should make the
> >> respective commits a bit easier to access. For example, we could put the
> >> equivalent of `git rev-parse --reference <commit>` here for each of the
> >> sides.
> >
> > Personally I'm not sure if the commit ID would do much for me, but I feel
> > like it would help me if it were possible to include the commit message. 
> 
> It would also help the resolution, not just committing after you are
> done.  It may not matter while picking between cherry and banana to
> show your personal preference on fruits, but in a more involved
> conflicted merge, it may help to be able to view "git show $commit",
> "git diff ...$commit", and "git diff $commit..." where $commit is
> the "add-fruit" side of the merge to understand what they wanted to
> do, and what we have done while they weren't looking.

Yup. Doesn't mean we cannot _also_ include the names that we have above. So in the above example it could be for example:

+FRUITS = [
+    "apple",
+<<<<<<< HEAD: abcdefg (fruits: add apple, 2026-10-01)
+    "cherry",
+=======
+    "banana",
+>>>>>>> add-fruit: 12345678 (fruits: add banana, 2024-02-03)

That format would have a bunch of advantages:

  - We don't have to teach users about special refs like MERGE_HEAD to
    let them figure out how to access each of the commits.

  - It gives a bit more context about what each specific side does, at
    least if you have good commit messages.

  - It also gives a sense of timing because we include dates, and that
    may help in some situations to figure out what's what.

I'll create an issue on the GitLab side and ask someone in the team to maybe give this a try.

Show 13 quoted lines

> >> I tend to forget that by default, we only render ours/theirs in the
> >> conflict. I always feel like that makes it way harder to resolve
> >> conflicts as you don't have the context of what the code looked like
> >> originally. So I have diff3 configured locally for ages.
> >
> > Every time I show people diff3 someone tells me how happy they
> > are to learn it :)
> 
> Yes, we should encourage "merge.conflictstyle=diff3" (I feel about
> this strongly enough to think it should become the default).
> Knowing what the original was before one side wanted to say "cherry"
> while the other side wanted to say "banana" sometimes helps a great
> deal to decide what to do with the conflict.

I very much agree that it should be the default.

Patrick