>  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

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

> 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

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

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

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

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

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

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

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

> From: 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>
> ---
>  Documentation/git-cherry-pick.adoc | 23 ++++-------------------
>  1 file changed, 4 insertions(+), 19 deletions(-)
>
> diff --git a/Documentation/git-cherry-pick.adoc b/Documentation/git-cherry-pick.adoc
> index f4cd8b9db7..d93829600b 100644
> --- a/Documentation/git-cherry-pick.adoc
> +++ b/Documentation/git-cherry-pick.adoc
> @@ -19,25 +19,9 @@ Given one or more existing commits, apply the change each one
>  introduces, recording a new commit for each.  This requires your
>  working tree to be clean (no modifications from the HEAD commit).
>  
> -When it is not obvious how to apply a change, the following
> -happens:
> -
> -1. The current branch and `HEAD` pointer stay at the last commit
> -   successfully made.
> -2. The `CHERRY_PICK_HEAD` ref is set to point at the commit that
> -   introduced the change that is difficult to apply, unless the
> -   `--no-commit` option was given.
> -3. Paths in which the change applied cleanly are updated both
> -   in the index file and in your working tree.
> -4. For conflicting paths, the index file records up to three
> -   versions, as described in the "TRUE MERGE" section of
> -   linkgit:git-merge[1].  The working tree files will include
> -   a description of the conflict bracketed by the usual
> -   conflict markers `<<<<<<<` and `>>>>>>>`.
> -5. No other modifications are made.
> -
> -See linkgit:git-merge[1] for some hints on resolving such
> -conflicts.
> +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.

>  
>  OPTIONS
>  -------
> @@ -259,6 +243,7 @@ $ git cherry-pick -Xpatience topic^  <4>
>  SEE ALSO
>  --------
>  linkgit:git-revert[1]
> +linkgit:gitmergeconflicts[7]
>  
>  GIT
>  ---

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

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

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

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

> The fact that cleanly auto-resolved contents for paths are recorded
> in the index may be shared with all other merge-like operations,
> and it need not be part of the "how to resolve a conflicted
> merge-like operation" recipe, but users need to be assured that this
> is what happens somewhere in the documentation set.  The list
> removed here served that purpose for this specific command, but it
> is now gone.

> My best guess (based on what you said) is that `CHERRY_PICK_HEAD` is
> only useful if you're cherry-picking multiple commits at the same time.
> Is the following an accurate explanation?:
>
>> If the conflict happened when cherry picking multiple commits, you can run
>> `git show CHERRY_PICK_HEAD` to see the commit that Git failed to apply.

> > 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).
> 
> Thanks, will fix this (and will move the conflict-marker-size change).
> 
> Should I be trying to apply my patches to `seen` before submitting them?

> On Mon, Sep 28, 2026 at 04:41:54PM -0400, Julia Evans wrote:
>
>> > 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).
>> 
>> Thanks, will fix this (and will move the conflict-marker-size change).
>> 
>> Should I be trying to apply my patches to `seen` before submitting them?
>
> In general, no, you don't have to. In this case it turned up useful
> ...
> If you do want to look ahead, I think "next" or "jch" is often a more
> useful target.

> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
> new file mode 100644
> index 0000000000..612b683e40
> --- /dev/null
> +++ b/Documentation/gitmergeconflicts.adoc
> @@ -0,0 +1,294 @@
> +gitmergeconflicts(7)
> +====================
> +
> +NAME
> +----
> +gitmergeconflicts - Guide to handling merge conflicts
> +
> +
> +SYNOPSIS
> +--------
> +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 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.

> +[[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

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

> +    "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.
> +
> +
> +[[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 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",
> +]
> +----
> +
> +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",
> +]
> +----
> +
> +
> +[[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.

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

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

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

>> +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]?

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

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

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

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

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

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

>>> +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 :)

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

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

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

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

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

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

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

>>>> +FRUITS = [
>>>> +    "apple",
>>>> +<<<<<<< HEAD
>>>> +    "cherry",
>>>> +=======
>>>> +    "banana",
>>>> +>>>>>>> add-fruit
>
>> 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.

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

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

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

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

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

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

> Marie and I worked on the OURS AND THEIRS section today and I think it's clearer
> now but also longer (instead of shorter which was my dream). We added an attempt
> at humor at the end to hopefully help things a bit.
>
> 	"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`.
>
> 	"Ours" and "theirs" are both commits: "ours" is the current
> 	`HEAD` commit, and "theirs" is the other side being merged.
>
> 	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.

> 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 (?).

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

>> 	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.
>
> May I ask what is in scope for this effort?
>
> We previously discussed updating the conflict markers (the 'HEAD'
> and 'add-fruit' labels in the example above).  Doing so would
> require code changes, which goes beyond mere documentation updates.
> But if a minor code change like that makes the documentation much
> easier to understand, I think we should consider doing so.
>
> Along the same line, if git status stopped saying "deleted by us"
> and instead used a different phrase, would that help reduce the
> "upside down" confusion [*]?  Is it acceptable to bend the code
> a little if it helps the documentation?

> [Footnote]
>
>  * I suspect that the "upside down" feeling is not really about the
>    terms "ours" and "theirs" themselves.  Rather, it comes from how
>    one conceptualizes what 'rebase' does compared to 'merge'.
>    During a rebase, we temporarily pretend that we are working on
>    the upstream branch and replay our local changes on top of it.
>    Once the user adopts this mindset, displaying the upstream state
>    first (the point from which we start building the consolidated
>    history) followed by the local state (what was done differently
>    by the local side) becomes consistent with how 'merge' displays
>    conflicts (where we start from our local state and merge the
>    incoming changes).