Add new page on merge conflicts

 Documentation/Makefile               |   1 +
 Documentation/gitmergeconflicts.adoc | 294 +++++++++++++++++++++++++++
 Documentation/meson.build            |   1 +
 3 files changed, 296 insertions(+)
 create mode 100644 Documentation/gitmergeconflicts.adoc

Documentation/Makefile +0 -0

index f8dea4b395..bc49641dda 100644

This unfortunately needs to be accompanied with a matching change to help the other build system.

You probably want to move your change to set conflict-marker-size for this new file to this step, not at the end as if an afterthought.

 Documentation/meson.build | 1 +
 1 file changed, 1 insertion(+)

Documentation/meson.build +1 -0

index 51647957e0..10b0637991 100644
@@ -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,

Documentation/gitmergeconflicts.adoc new file +8 -0

new file mode 100644
index 0000000000..612b683e40
@@ -0,0 +1,294 @@
+gitmergeconflicts(7)
+====================
+
+NAME
+----
+gitmergeconflicts - Guide to handling merge conflicts
+
+

Documentation/gitmergeconflicts.adoc new file +19 -0

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

Documentation/gitmergeconflicts.adoc new file +12 -0

+[[example]]
+EXAMPLE OF RESOLVING A MERGE CONFLICT
+-------------------------------------
+
+If you see this in your code during a merge conflict:
+
+----
+FRUITS = [
+    "apple",
+<<<<<<< HEAD
+    "cherry",
+    "mango",

Documentation/gitmergeconflicts.adoc new file +12 -0

+----
+FRUITS = [
+    "apple",
+    "banana",
+    "cherry",
+    "mango",
+    "orange",
+]
+----
+
+
+[[tools]]

Documentation/gitmergeconflicts.adoc new file +5 -0

+[[ours]]
+"OURS" AND "THEIRS"
+-------------------
+
+Git refers to the first part of a merge conflict (between `<<<<<<<`

Documentation/gitmergeconflicts.adoc line 18

Quoted 2 lines

Documentation/gitmergeconflicts.adoc new file +2 -0

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

Documentation/gitmergeconflicts.adoc line 29

Quoted 8 lines

Documentation/gitmergeconflicts.adoc new file +8 -0

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

Documentation/gitmergeconflicts.adoc line 37

Quoted 6 lines

+[[markers]]

Documentation/gitmergeconflicts.adoc new file +5 -0

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

Documentation/gitmergeconflicts.adoc line 78

Quoted 2 lines

Documentation/gitmergeconflicts.adoc new file +2 -0

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

s/the the/the/

Documentation/gitmergeconflicts.adoc line 49

Quoted 12 lines

Documentation/gitmergeconflicts.adoc new file +12 -0

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

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.

Documentation/gitmergeconflicts.adoc line 125

Quoted 5 lines

Documentation/gitmergeconflicts.adoc new file +5 -0

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

Quoted 5 lines

+[[ours]]
+"OURS" AND "THEIRS"
+-------------------

Documentation/gitmergeconflicts.adoc new file +2 -0

+
+Git refers to the first part of a merge conflict (between `<<<<<<<`

Documentation/gitmergeconflicts.adoc line 243

Quoted 10 lines

Documentation/gitmergeconflicts.adoc new file +10 -0

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

Quoted 4 lines

Documentation/gitmergeconflicts.adoc new file +4 -0

+These terms in Git all mean the same thing when dealing with a merge
+conflict:
+
+* "common ancestor", "base", and "stage 1"

Documentation/gitmergeconflicts.adoc line 250

Quoted 2 lines

Documentation/gitmergeconflicts.adoc new file +2 -0

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

Quoted 14 lines

Documentation/gitmergeconflicts.adoc line 49

Quoted 12 lines

Documentation/gitmergeconflicts.adoc new file +12 -0

+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

Quoted 4 lines

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.

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

Quoted 14 lines · Julia Evans

Quoted 14 lines

Documentation/gitmergeconflicts.adoc line 49

Quoted 12 lines

Documentation/gitmergeconflicts.adoc new file +12 -0

+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

Quoted 7 lines

Quoted 4 lines

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.

Quoted 5 lines

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

Quoted 2 lines

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.

Documentation/gitmergeconflicts.adoc new file +7 -0

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

Quoted 7 lines

Quoted 7 lines

Quoted 7 lines

Documentation/gitmergeconflicts.adoc new file +7 -0

+FRUITS = [
+    "apple",
+<<<<<<< HEAD
+    "cherry",
+=======
+    "banana",
+>>>>>>> add-fruit

Quoted 2 lines

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.

Quoted 29 lines

[snip]

Quoted 5 lines

+[[ours]]
+"OURS" AND "THEIRS"
+-------------------

Documentation/gitmergeconflicts.adoc new file +2 -0

+
+Git refers to the first part of a merge conflict (between `<<<<<<<`

Documentation/gitmergeconflicts.adoc line 243

Quoted 10 lines

Documentation/gitmergeconflicts.adoc new file +10 -0

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

Quoted 7 lines

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.

Quoted 4 lines

Quoted 4 lines

Documentation/gitmergeconflicts.adoc new file +4 -0

+These terms in Git all mean the same thing when dealing with a merge
+conflict:
+
+* "common ancestor", "base", and "stage 1"

Quoted 8 lines

Documentation/gitmergeconflicts.adoc line 250

Quoted 2 lines

Documentation/gitmergeconflicts.adoc new file +2 -0

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

Quoted 11 lines

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

Quoted 5 lines

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

From: Julia Evans <[email protected]>

All of the info about merge conflicts has been moved to the new guide

Among the changes made to the common ancestor's version,

Hi Julia,

Quoted 6 lines · Julia Evans via GitGitGadget

From: Julia Evans <[email protected]>

All of the info about merge conflicts has been moved to the new guide

Among the changes made to the common ancestor's version,

Documentation/git-merge.adoc git merge v1.2.3^0

Quoted 9 lines

Documentation/git-merge.adoc +0 -8

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

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.

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.

Quoted 3 lines

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.

Quoted 3 lines · "Julia Evans

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.

Quoted 8 lines · Junio C Hamano

Quoted 3 lines · "Julia Evans

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.

Quoted 3 lines

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



Quoted 2 lines · D. Ben Knoble

Hi Julia,

Quoted 7 lines

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:

Quoted 3 lines

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.

Quoted 19 lines · D. Ben Knoble

Hi Julia,

Documentation/git-merge.adoc git merge v1.2.3^0 · line 243

Quoted 11 lines · Julia Evans via GitGitGadget

From: Julia Evans <[email protected]>

All of the info about merge conflicts has been moved to the new guide

Among the changes made to the common ancestor's version,

Documentation/git-merge.adoc +0 -5

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

Quoted 3 lines

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!

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.

Quoted 7 lines

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.

Quoted 4 lines

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

Quoted 1 line

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

Quoted 20 lines · Julia Evans

Quoted 19 lines · D. Ben Knoble

Hi Julia,

Documentation/git-merge.adoc git merge v1.2.3^0 · line 243

Quoted 11 lines · Julia Evans via GitGitGadget

From: Julia Evans <[email protected]>

All of the info about merge conflicts has been moved to the new guide

Among the changes made to the common ancestor's version,

Documentation/git-merge.adoc +0 -5

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

Quoted 5 lines

Quoted 3 lines

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.

PS Unlike Junio---perhaps due to my lack of older Git history and terminology, despite using Git since 2016?---I would never have read "unstaged" as *deleted* from the index. Just changed and not updated in the index (i.e., not "git add"-ed).

From: Julia Evans <[email protected]>

All of the info about merge conflicts has been moved to the new guide

From: Julia Evans <[email protected]>

Remove the discussion of merge conflicts and replace it with a link to the guide.

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-cherry-pick.adoc | 23 ++++-------------------
 1 file changed, 4 insertions(+), 19 deletions(-)

Documentation/git-cherry-pick.adoc +0 -12

index f4cd8b9db7..d93829600b 100644
@@ -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

Documentation/git-cherry-pick.adoc +1 -0

 OPTIONS
 -------

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

The new document may explain how to resolve conflicts, but are the details removed from here that are specific to the 'cherry-pick' operation also covered there?

For example, during a difficult cherry-pick, it is often handy to be able to run 'git show CHERRY_PICK_HEAD', but now users are not told about the pseudo-ref, which seems like a real loss.

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.

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

Quoted 2 lines

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.

Subject: Re: [PATCH 7/7] [doc] ignore conflict markers in gitmergeconflicts.adoc
From: Julia Evans <[email protected]>

Signed-off-by Julia Evans <[email protected]>

---
 .gitattributes | 1 +
 1 file changed, 1 insertion(+)

.gitattributes +0 -0

index 26490ad60a..0a0fc950b1 100644

Quoted 17 lines · Julia Evans via GitGitGadget

Subject: Re: [PATCH 7/7] [doc] ignore conflict markers in gitmergeconflicts.adoc
From: Julia Evans <[email protected]>

Signed-off-by Julia Evans <[email protected]>

---
 .gitattributes | 1 +
 1 file changed, 1 insertion(+)

.gitattributes +1 -0

index 26490ad60a..0a0fc950b1 100644
@@ -14,6 +14,7 @@ CODE_OF_CONDUCT.md -whitespace
 /t/oid-info/* text eol=lf
 /Documentation/git-merge.adoc conflict-marker-size=32
 /Documentation/git-merge-file.adoc conflict-marker-size=32
+/Documentation/gitmergeconflicts.adoc conflict-marker-size=32

.gitattributes CODE_OF_CONDUCT.md -whitespace · line 20

Quoted 3 lines

.gitattributes +0 -0

 /Documentation/gitk.adoc conflict-marker-size=32
 /Documentation/user-manual.adoc conflict-marker-size=32
 /t/t????-*.sh conflict-marker-size=32

I believe the
plan is to squash this into the step that introduces the new file; when that happens, the patch title will disappear and we will not have to worry about it

By the way, some of the points above might be worth teaching in the material covering merge conflicts (i.e., this series). I do not think many people write manuals on Git with examples of what a conflict block looks like ;-), but a run of seven '<', '=', '|', or '>' characters may appear in real payloads that users need to use, in contexts completely unrelated to ours.

Setting 'conflict-marker-size' to a length that their payload is unlikely to use is a useful technique to be aware of.

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

Quoted 8 lines · Julia Evans via GitGitGadget

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

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

Quoted 2 lines

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?

Quoted 3 lines · Julia Evans

Quoted 2 lines

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

Quoted 3 lines

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.

A topic on the seen branch just means it was seen by the maintainer, and might not even pass all of the tests. Whereas "next" is fairly stable, and "jch" is (I believe) what Junio runs day to day (so a subset of "seen" that seems pretty stable).

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.

Also if/when the git rebase --squash changes land, then we'd need
to add git history to this 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.

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

Quoted 2 lines

* 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

Quoted 2 lines

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.

Thanks for the review!

Quoted 5 lines

Quoted 2 lines

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

Quoted 14 lines · Julia Evans

Thanks for the review!

Quoted 5 lines

Quoted 2 lines

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

Quoted 5 lines

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

Quoted 7 lines

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

I was actually surprised to discover that git status does not recommend git merge --continue: it recommends git commit.

Maybe we should change that though?

I agree it makes sense to be consistent with what git status recommends.

Quoted 8 lines

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

The only other thing that gives me pause about recommending folks git merge --continue too strongly is that as we know Git users are slow to change their habits, and we don't want to confuse anyone. If someone is currently using git commit I want to know that they can keep doing it the same way with no worries.

Maybe if we change git status to recommend git merge --continue, and we think there are no real advantages to using git commit instead of git merge --continue, then we could say something like this:

NOTE: git commit is an older alternative to git merge --continue. You can use either one after resolving a git merge.

I'd love to hear from others on either changing status output to recommend "merge --continue" or admitting that, for merges, "commit" is the same thing.

From: Julia Evans <[email protected]>

Introduce a new page, gitmergeconflicts, that explains the process of handling a merge conflict in a way that addresses the following issues, which came from feedback from Git users on the current explanation of merge conflicts in the git merge man page:

- The process for resolving a merge conflict is only explained in the git merge man page, even though there are several other commands which can result in conflicts
- Sometimes we use "ours" and "theirs" to refer to the two sides of the merge conflicts and sometimes we use HEAD and MERGE_HEAD. It should be consistent. Also the terms "ours" and "theirs" are not explained. Similarly, it says "The part before the ======= is typically your side...", but doesn't explain what "typically" means.
- It introduces the merge format using an analogy to RCS, which very few Git users have ever used
- In "The only clean-ups you need are to reset the index file to the

HEAD commit to reverse 2. and to clean up working tree changes made by 2. and 3.", it's not clear to users what "2" and "3" are supposed to mean
- It uses a cultural reference ("Conflict resolution is hard; let's go shopping.") which is confusing or unfamiliar to some people. I think it would be clearer for users to use a code example instead.
- It doesn't explain the difference between diff3 and zdiff3
- It sometimes uses the term "area" and sometimes uses the term "hunk"

Also document the unified --abort, --continue workflow in one place, since it's a really nice example of a place Git has a consistent interface between similar commands.

Co-Authored-By Marie Claire LeBlanc Flanagan <[email protected]>

Reviewed-by D. Ben Knoble <[email protected]>

Reviewed-by Patrick Steinhardt <[email protected]>

Signed-off-by Julia Evans <[email protected]>

Documentation/gitmergeconflicts.adoc new file +4 -0

new file mode 100644
index 0000000000..5b0ba1a1de
@@ -0,0 +1,333 @@
+gitmergeconflicts(7)
+====================
+
+NAME

Documentation/gitmergeconflicts.adoc new file +10 -0

+For example, here's a merge conflict where both sides edited a list of
+fruits in different ways:
+
+----
+FRUITS = [
+    "apple",
+<<<<<<< HEAD
+    "cherry",
+=======
+    "banana",

Documentation/gitmergeconflicts.adoc new file +29 -0

+[[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 same thing.
+
+
+[[example]]
+EXAMPLE OF RESOLVING A MERGE CONFLICT
+-------------------------------------
+
+If you see this in your code during a merge conflict:
+
+----
+FRUITS = [
+    "apple",

Documentation/gitmergeconflicts.adoc new file +4 -0

+[[tools]]
+TOOLS FOR HANDLING MERGE CONFLICTS
+----------------------------------
+

Documentation/gitmergeconflicts.adoc new file +4 -0

+[[git_status]]
+EXAMPLE: GIT STATUS OUTPUT
+--------------------------
+

Documentation/gitmergeconflicts.adoc new file +11 -0

+----
+FRUITS = [
+    "apple",
+<<<<<<< HEAD
+    "cherry",
+    "mango",
+||||||| 1c22e48
+    "mangoooo",
+=======
+    "banana",
+    "mango",

Documentation/gitmergeconflicts.adoc new file +31 -0

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

Documentation/gitmergeconflicts.adoc new file +6 -0

+For example, if we resolved the conflict by adding both "banana" and
+"cherry" in order, the diff would look like this:
+
+----
+ FRUITS = [
+     "apple",

- In "The only clean-ups you need are to reset the index file to the HEAD commit to reverse 2. and to clean up working tree changes made by 2. and 3.", it's not clear to users what "2" and "3" are supposed to mean

Quoted 4 lines

Co-Authored-By Marie Claire LeBlanc Flanagan <[email protected]>

Reviewed-by D. Ben Knoble <[email protected]>

Reviewed-by Patrick Steinhardt <[email protected]>

Signed-off-by Julia Evans <[email protected]>

We want a sign-off by the coauthor, too.

Quoted 16 lines

Documentation/gitmergeconflicts.adoc new file +10 -0

new file mode 100644
index 0000000000..5b0ba1a1de
@@ -0,0 +1,333 @@
+gitmergeconflicts(7)
+====================
+
+NAME
+----
+gitmergeconflicts - Guide to handling merge conflicts
+
+DESCRIPTION
+-----------
+

Documentation/gitmergeconflicts.adoc line 14

Quoted 4 lines

Documentation/gitmergeconflicts.adoc new file +4 -0

+Merge conflicts can happen during a `git merge`, `git rebase`, `git
+cherry-pick`, `git pull`, or `git revert`. All of those commands use
+the same merge algorithm, and the process for resolving a merge conflict
+is always very similar.

Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order to limit ourselves to most common ways to help new people by keeping the description to the absolute minimum?

In any case, the first paragraph clearly stating that conflicts happen with operations other than 'merge' is a very welcome change. On this list, we often say "mergy operations can cause conflicts", with the understanding that readers know what mergy operations are and "conflicts" alone can convey the state you call "merge conflicts" in this document. But in a document for end-users, using a longer term "merge conflicts" instead of "conflicts" and avoiding "mergy operations" like you did above may be a better direction to go.

Documentation/gitmergeconflicts.adoc line 16

Quoted 1 line

Documentation/gitmergeconflicts.adoc new file +1 -0

+The most common ways to handle a merge conflict are:

A natural paraphrase of the above is "A merge conflict is typically handled by these ways", but I thought the current readers are puzzled by "typically your side" that does not say when is typical.

Documentation/gitmergeconflicts.adoc line 23

Quoted 6 lines

Documentation/gitmergeconflicts.adoc new file +6 -0

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

Both are good options and I do not think of a middle way. Perhaps we do not have to say that these are "the most common" and instead say "You handle a merge conflict by doing either of these two"?

Saying "return your branch to" is a bit misleading for two reasons. Conflicts presented to the users are primarily visible in their working tree files and the index. A single commit operations like 'merge', 'pull', and 'revert' does not touch your branch if they hit a conflict, and 'rebase' works on a detached HEAD, and stops without touching your branch when it sees a conflict.

If I were writing this, with the goal of avoiding the issues the current text has you listed in the proposed log message, I would probably say something like this:

* Or give up and return to the original state with ...

Documentation/gitmergeconflicts.adoc line 31

Quoted 8 lines

Documentation/gitmergeconflicts.adoc new file +7 -0

+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
+the same file, then it can easily combine them since there's no overlap.

Many of the operations, even "git merge", is not about merging "two commits" together, but I do not think of a good way to explain it, so I accept that phrasing as a helpful white lie. I mention this because somebody else may be able to come up with a better phrasing that I (or authors of this iteration) couldn't think of.

Documentation/gitmergeconflicts.adoc line 44

Quoted 12 lines

Documentation/gitmergeconflicts.adoc new file +12 -0

+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 marks them as conflicted, puts both
+  sides' edits in the file, and leaves <<markers, merge conflict markers>>
+  that you need to resolve.

By the way, I think we should briefly mention what sematnic merge conflicts are, and that Git does not detect them and that this manual page does not tell readers how to deal with them.

Note that non-overlapping changes from two sides may leave the result in an inconsistent state. With the edit to lines 1-5, one side may have changed the name of a function, while with the edit to lines 20-25, the other side may have added a new call to the function by its original name. This type of inconsistencies are called semantic conflicts, Git has no way knowing that a merge introduced semantic conflicts, and ends up producing a broken result without merge conflicts. This document does not cover what to do with semantic conflicts.

That is overly long, but perhaps you can condense it down to the essense and shrink down to 1/3 of the size.

Documentation/gitmergeconflicts.adoc line 51

Quoted 6 lines

Documentation/gitmergeconflicts.adoc new file +6 -0

+[[markers]]
+MERGE CONFLICT MARKERS
+----------------------
+
+When there's a merge conflict, Git will update the conflicted file
+to include merge conflict markers `<<<<<<<`, `=======`, and `>>>>>>>`.

I notice that when you introduce diff3 below, you silently add ||||||| to the mix without explaining what it is.

    `|||||||` may also be used as merge conflict markers (explained
    later).

or something along the line here may help. Or explain what it is in diff3 section. Either would work. Adding without explanation would not.

Quoted 17 lines

Documentation/gitmergeconflicts.adoc new file +17 -0

+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

Documentation/gitmergeconflicts.adoc line 71

Quoted 3 lines

Documentation/gitmergeconflicts.adoc new file +3 -0

+`=======`, 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.

If we said "one side wanted to have 'apple, cherry, mango, orange', while the other side wanted 'apply, banana, mango, orange', in the FRUITS array", would it help the understanding? Or is it too obvious?

Quoted 18 lines

Documentation/gitmergeconflicts.adoc new file +18 -0

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

Documentation/gitmergeconflicts.adoc line 85

Quoted 1 line

Documentation/gitmergeconflicts.adoc new file +1 -0

+----

It would make your readers puzzled why the example is subtly different from the earlier one that showed "mango" as not touched by either side. I see this lays the groundwork for later demonstration of diff3, so having both sides explicitly want "mango" is a good example. Perhaps update the first example to be the same as this one, which would reduce the mental burden by readers?

Quoted 10 lines

Documentation/gitmergeconflicts.adoc new file +10 -0

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

Documentation/gitmergeconflicts.adoc line 141

Quoted 4 lines

Documentation/gitmergeconflicts.adoc new file +4 -0

+  the mergetools Git supports.
+
+* You can set the configuration option `merge.conflictstyle=diff3`.
+  See <<diff3,DIFF3 AND ZDIFF3>> below for more.

These are called 'configuration variables' throughout the manual pages. Be consistent and replace "configuration option" with "configuration variable", perhaps?

Documentation/gitmergeconflicts.adoc line 145

Quoted 3 lines

Documentation/gitmergeconflicts.adoc new file +3 -0

+* `git log --merge -p <filename>`  will list all commits which
+  caused the merge conflict for `<filename>`, and the diff
+  of how they changed the file.

Maybe worth mentioning that --left-right often helps when you are not super familiar with the histories being merged.

Documentation/gitmergeconflicts.adoc line 150

Quoted 4 lines

Documentation/gitmergeconflicts.adoc new file +4 -0

+* Look at the original files.  `git show :1:filename` shows the
+  common ancestor, `git show :2:filename` shows the "ours"
+  version, and `git show :3:filename` shows the "theirs"
+  version.

Maybe it will help to say we will explain "ours" and "theirs" later in this document.

Documentation/gitmergeconflicts.adoc line 161

Quoted 2 lines

Documentation/gitmergeconflicts.adoc new file +2 -0

+* Use `git diff AUTO_MERGE` to show what changes you've made so far to
+  resolve the conflicts.

Does a "See below" here help readers who haven't learned what AUTO_MERGE is? If you can describe what AUTO_MERGE records (in other words, what you are comparing your progress against) in a sentence of two here, that would alleviate the need to assure them that we have more in-depth coverage on this topic elsewhere.

Quoted 4 lines

Documentation/gitmergeconflicts.adoc new file +4 -0

+[[git_status]]
+EXAMPLE: GIT STATUS OUTPUT
+--------------------------
+

Documentation/gitmergeconflicts.adoc line 176

Quoted 10 lines

Documentation/gitmergeconflicts.adoc new file +10 -0

+When you're in a merge conflict, you can find out what commands to run
+to handle the conflict by running `git status`.
+
+For example, this `git status` output tells you that:
+
+* `git rebase --abort` will safely bring your branch back to its
+  original state
+* you should run `git rebase --continue` when you're done resolving all
+  the conflicts
+* there's one file left with conflicts in it: `fruits.py`

There may be users, after seeing the last point, left puzzled why fruits.py is still listed after they edited the file like instructed in an earlier example but haven't marked the resolution.

fruits.py is not marked as its conflicts resolved yet.

or something?

Quoted 9 lines

Documentation/gitmergeconflicts.adoc new file +9 -0

+----
+$ git status
+You are currently rebasing branch 'main' on '58a9fcc'.
+  (fix conflicts and then run "git rebase --continue")
+  (use "git rebase --skip" to skip this patch)
+  (use "git rebase --abort" to check out the original branch)
+
+Unmerged paths:
+  (use "git restore --staged <file>..." to unstage)

Documentation/gitmergeconflicts.adoc line 189

Quoted 3 lines

Documentation/gitmergeconflicts.adoc new file +3 -0

+  (use "git add <file>..." to mark resolution)
+        both modified:   fruits.py
+----

The approach to give explanations first and then an example the explanation explains next is refreshing to me. As long as the explanations are short enough, this may work better than the usual order to say "you'd see something like this. let us explain ...".

Quoted 4 lines

Documentation/gitmergeconflicts.adoc new file +4 -0

+[[diff3]]
+DIFF3 AND ZDIFF3
+----------------
+

Documentation/gitmergeconflicts.adoc line 200

Quoted 5 lines

Documentation/gitmergeconflicts.adoc new file +5 -0

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

I think most on the list considers zdiff3 a failed experiment that reduces usefulness of diff3. Do we want to recommend it?

By the way, is it just me who finds those "Here's", "there's" contractions disturbing in an official manual? I've seen many of them while reviewing this to be annoyed enough and had to blurt it out X-<.

Documentation/gitmergeconflicts.adoc line 255

Quoted 2 lines

Documentation/gitmergeconflicts.adoc new file +2 -0

+"Ours" and "theirs" are both commits: "ours" is the current
+`HEAD` commit, and "theirs" is the other side being merged.

Now, "commits" is again a white lie. The story becomes more complicated when we talk about cherry-pick and revert, but if we primarily stick to what happens in 'merge' (which is what I've seen so far in this document), then it shouldn't add any extra difficulty to understand by saying "ours and theirs are history of changes leading to the two commits since they diverged from the original" to add clarity.

Quoted 31 lines

Documentation/gitmergeconflicts.adoc new file +31 -0

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

Documentation/gitmergeconflicts.adoc line 297

Quoted 10 lines

Documentation/gitmergeconflicts.adoc new file +10 -0

+Finding the commit that deleted the file and seeing why is usually more
+helpful than trying to abstractly reason through what "us" means.
+
+[[automerge]]
+EXAMPLE OF USING `AUTO_MERGE`
+-----------------------------
+
+`git diff AUTO_MERGE` will show what changes you've made so far to
+resolve conflicts. `AUTO_MERGE` is a reference that Git creates during a
+merge. It contains the result of running the merge algorithm.

The first sentence gave me "Huh? You haven't explained what AUTO_MERGE is yet". It may be just me, but I would have expected presentation order to be more like:

When merge conflicts happen, the result of merge algorithm, together with conflict markers, is recorded in AUTO_MERGE. As you resolve conflicts, you can compare your working tree files against it with git diff AUTO_MERGE to see your progress.

Quoted 6 lines

Documentation/gitmergeconflicts.adoc new file +6 -0

+For example, if we resolved the conflict by adding both "banana" and
+"cherry" in order, the diff would look like this:
+
+----
+ FRUITS = [
+     "apple",

Documentation/gitmergeconflicts.adoc line 314

Quoted 10 lines

Documentation/gitmergeconflicts.adoc new file +10 -0

+-<<<<<<< HEAD
+-    "cherry",
+-=======
+     "banana",
+->>>>>>> add-fruit
++    "cherry",
+     "mango",
+     "orange",
+ ]
+----

Thanks.

I was puzzled by this

Quoted 4 lines

- In "The only clean-ups you need are to reset the index file to the HEAD commit to reverse 2. and to clean up working tree changes made by 2. and 3.", it's not clear to users what "2" and "3" are supposed to mean

and did some digging.

The text comes from ffb1a4bed5 (Documentation: Describe merge operation a bit better., 2005-11-28) that had "When there are conflicts, these things happen. 1. HEAD does not move, 2. Cleanly merged paths are updated in the index 3. Conflicts are recorded in higher stage index entries and working tree files show conflict markers, 4. No other changes are done" well before the mysterious reference to 2. and 3.

When ebef7e5049 (Documentation: simplify How Merge Works, 2010-01-23) tried to simplify the description, the list of "these things happen" were removed/rewritten, and yet instructions on how to reset are left behind, still referring to 2. and 3.

We probably want a separate patch for Documentation/git-merge.adoc to rectify this 16 year old mistake.

Quoted 10 lines

Documentation/gitmergeconflicts.adoc line 23

Quoted 6 lines

Documentation/gitmergeconflicts.adoc new file +6 -0

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

Both are good options and I do not think of a middle way. Perhaps we do not have to say that these are "the most common" and instead say "You handle a merge conflict by doing either of these two"?

I agree the "the most common" is kind of weaselly and I'd like to be more clear. The reason I wrote "typically" is that during a rebase, there's an extra "skip" option, so it's not strictly true to say that there are just two options. Not sure if there's another option I'm not thinking of other than the "skip" in rebase.

I was thinking about that too. Maybe we can briefly mention that git's merges are not guaranteed to produce working code even when they succeed and point to an example further down the page. Added to my list of things to work on.

Quoted 10 lines

Quoted 10 lines

+[[tools]]

Documentation/gitmergeconflicts.adoc new file +9 -0

+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

Quoted 8 lines

Documentation/gitmergeconflicts.adoc line 141

Quoted 4 lines

Documentation/gitmergeconflicts.adoc new file +4 -0

+  the mergetools Git supports.
+
+* You can set the configuration option `merge.conflictstyle=diff3`.
+  See <<diff3,DIFF3 AND ZDIFF3>> below for more.

These are called 'configuration variables' throughout the manual pages. Be consistent and replace "configuration option" with "configuration variable", perhaps?

They seem to be both used interchangeably already:

```
$ grep 'configuration variable' *.adoc | wc -l
     256
$ grep 'configuration option' *.adoc | wc -l
      46
```

Quoted 6 lines

Documentation/gitmergeconflicts.adoc line 145

Quoted 3 lines

Documentation/gitmergeconflicts.adoc new file +3 -0

+* `git log --merge -p <filename>`  will list all commits which
+  caused the merge conflict for `<filename>`, and the diff
+  of how they changed the file.

Maybe worth mentioning that --left-right often helps when you are not super familiar with the histories being merged.

I don't understand what this does or what it would be useful for so it's not possible for me to explain it :). From my perspective "ours" and "theirs" are already confusing enough and introducing "left" and "right" seems like a lot. Is "left" the same as "ours"?

Quoted 8 lines

Documentation/gitmergeconflicts.adoc line 161

Quoted 2 lines

Documentation/gitmergeconflicts.adoc new file +2 -0

+* Use `git diff AUTO_MERGE` to show what changes you've made so far to
+  resolve the conflicts.

Does a "See below" here help readers who haven't learned what AUTO_MERGE is? If you can describe what AUTO_MERGE records (in other words, what you are comparing your progress against) in a sentence of two here, that would alleviate the need to assure them that we have more in-depth coverage on this topic elsewhere.

I think this is okay the way it is.

Maybe we could add a note like this somewhere?

NOTE: zdiff3 was an experimental alternative to diff3 that makes the merge conflict shorter by introducing more ambiguity. It's still there for backwards compatibility but we don't recommend it.

Quoted 4 lines

By the way, is it just me who finds those "Here's", "there's" contractions disturbing in an official manual? I've seen many of them while reviewing this to be annoyed enough and had to blurt it out X-<.

I find "here is" and "there is" to be distracting and overly formal, different people are different I guess :)

Quoted 13 lines

The text comes from ffb1a4bed5 (Documentation: Describe merge operation a bit better., 2005-11-28) that had "When there are conflicts, these things happen. 1. HEAD does not move, 2. Cleanly merged paths are updated in the index 3. Conflicts are recorded in higher stage index entries and working tree files show conflict markers, 4. No other changes are done" well before the mysterious reference to 2. and 3.

When ebef7e5049 (Documentation: simplify How Merge Works, 2010-01-23) tried to simplify the description, the list of "these things happen" were removed/rewritten, and yet instructions on how to reset are left behind, still referring to 2. and 3.

Quoted 2 lines

We probably want a separate patch for Documentation/git-merge.adoc to rectify this 16 year old mistake.

Thanks for investigating!

Quoted 3 lines

Is it deliberate to omit 'am -3' and 'checkout -m', perhaps in order to limit ourselves to most common ways to help new people by keeping the description to the absolute minimum?

It's deliberate, we talked about that a bit in the discussion of the v1. Can add a note in the commit message.

Quoted 4 lines

By the way, is it just me who finds those "Here's", "there's" contractions disturbing in an official manual? I've seen many of them while reviewing this to be annoyed enough and had to blurt it out X-<.

I find "here is" and "there is" to be distracting and overly formal, different people are different I guess :)

From: Julia Evans <[email protected]>

All of the info about merge conflicts has been moved to the new guide

Documentation/git-merge.adoc +0 -0

@@ -231,127 +232,6 @@ git merge v1.2.3^0
 git merge --ff-only v1.2.3
 ----
 

Documentation/git-merge.adoc +0 -15

-By default, Git uses the same style as the one used by the "merge" program
-from the RCS suite to present such a conflicted hunk, like this:
-
-------------
-Here are lines that are either unchanged from the common
-ancestor, or cleanly resolved because only one side changed,
-or cleanly resolved because both sides changed the same way.
-<<<<<<< yours:sample.txt
-Conflict resolution is hard;
-let's go shopping.
-=======
-Git makes conflict resolution easy.
->>>>>>> theirs:sample.txt
-And here is another line that is cleanly resolved or unmodified.
-------------

Documentation/git-merge.adoc +0 -6

-HOW TO RESOLVE CONFLICTS
-------------------------
-
-After seeing a conflict, you can do two things:
-
- * Decide not to merge.  The only clean-ups you need are to reset

Documentation/git-merge.adoc +0 -8

-You can work through the conflict with a number of tools:
-
- * Use a mergetool.  `git mergetool` to launch a graphical
-   mergetool which will work through the merge with you.
-
- * Look at the diffs.  `git diff` will show a three-way diff,
-   highlighting changes from both the `HEAD` and `MERGE_HEAD`
-   versions. `git diff AUTO_MERGE` will show what changes you've

From: Julia Evans <[email protected]>

Remove some of the detail about how to handle a merge conflict, since it's explained in detail in the new guide, and there probably isn't enough detail anyway.

Leave the steps since rebase is special and has a --skip option which the other commands which cause merge conflicts don't have.

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-rebase.adoc | 13 +++++++++----
 1 file changed, 9 insertions(+), 4 deletions(-)

From: Julia Evans <[email protected]>

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-revert.adoc | 5 +++++
 1 file changed, 5 insertions(+)

Documentation/git-revert.adoc +0 -0

index ffba365e63..1edf98b9aa 100644

Documentation/git-revert.adoc +1 -0

 OPTIONS
 -------
 <commit>...::

@@ -162,6 +166,7 @@ include::config/revert.adoc[]
 SEE ALSO
 --------
 linkgit:git-cherry-pick[1]
+linkgit:gitmergeconflicts[7]
 
 GIT
 ---

Documentation/git-cherry-pick.adoc +2 -3

+When a merge conflict happens:
 
 1. The current branch and `HEAD` pointer stay at the last commit
    successfully made.

@@ -36,9 +39,6 @@ happens:
    conflict markers `<<<<<<<` and `>>>>>>>`.
 5. No other modifications are made.
 
-See linkgit:git-merge[1] for some hints on resolving such
-conflicts.
-
 OPTIONS
 -------
 <commit>...::

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

Documentation/git-cherry-pick.adoc Given one or more existing commits, apply the change each one · line 24

Quoted 5 lines · Julia Evans via GitGitGadget

Documentation/git-cherry-pick.adoc +3 -2

-When it is not obvious how to apply a change, the following
-happens:
+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.

"Obvious to whom" was the first thing that came to my mind, even though the blame largely lies on the original. Can't we get rid of the above pragraph altogether, and "See new one" at the end where you replaced "See git-merge" reference below?

Quoted 22 lines

Documentation/git-cherry-pick.adoc +2 -3

+When a merge conflict happens:
 
 1. The current branch and `HEAD` pointer stay at the last commit
    successfully made.

@@ -36,9 +39,6 @@ happens:
    conflict markers `<<<<<<<` and `>>>>>>>`.
 5. No other modifications are made.
 
-See linkgit:git-merge[1] for some hints on resolving such
-conflicts.
-
 OPTIONS
 -------
 <commit>...::

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

From: Julia Evans <[email protected]>

Signed-off-by Julia Evans <[email protected]>

---
 Documentation/git-pull.adoc | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

Documentation/git-pull.adoc +0 -0

index 88f4fd3926..73f6d460bb 100644

* [x] list reviewers in Reviewed-by

Range-diff vs v1:

1: ad4853dc36 ! 1: ab0344f947 [doc] Add new gitmergeconflicts man page
@@ Metadata
Author: Julia Evans <[email protected]>

## Commit message ##
- [doc] Add new gitmergeconflicts man page
+ doc: add new gitmergeconflicts man page
...

Co-Authored-By Marie Claire LeBlanc Flanagan <[email protected]>

+ Reviewed-by: D. Ben Knoble <[email protected]>
+ Reviewed-by: Patrick Steinhardt <[email protected]>

Signed-off-by Julia Evans <[email protected]>

Quoted 1 line · Julia Evans via GitGitGadget

* [x] list reviewers in Reviewed-by

We may have a bit of misunderstanding in the process regarding this.

. Reviewed-by:, unlike the other trailers, can only be offered by the
reviewers themselves when they are completely satisfied with the patch after a detailed analysis.

is how SubmittingPatches describes it.

Quoted 2 lines

"Julia Evans via GitGitGadget" <[email protected]> writes:

For example, you added Ben and Patrick to the trailer of patch #1.

Quoted 14 lines

Range-diff vs v1:

1: ad4853dc36 ! 1: ab0344f947 [doc] Add new gitmergeconflicts man page
@@ Metadata
Author: Julia Evans <[email protected]>

## Commit message ##
- [doc] Add new gitmergeconflicts man page
+ doc: add new gitmergeconflicts man page
...

Co-Authored-By Marie Claire LeBlanc Flanagan <[email protected]>

+ Reviewed-by: D. Ben Knoble <[email protected]>
+ Reviewed-by: Patrick Steinhardt <[email protected]>

Signed-off-by Julia Evans <[email protected]>

Julia Evans (6):
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

From: Julia Evans <[email protected]>

Introduce a new page, gitmergeconflicts, that explains the process of handling a merge conflict in a way that addresses the following issues, which came from feedback from Git users on the current explanation of merge conflicts in the git merge man page:

- The process for resolving a merge conflict is only explained in the
...
- It sometimes uses the term "area" and sometimes uses the term "hunk"

Only discuss merge, rebase, cherry-pick, and revert for now even though there are other ways that merge conflicts can happen because it's awkward to talk about am, apply, and checkout -m.

+----

Documentation/gitmergeconflicts.adoc +37 -0

+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.
 
 
 
 
+[[example]]
+EXAMPLE OF RESOLVING A MERGE CONFLICT
+-------------------------------------
+
+If you see this in your code during a merge conflict:
+
+----
+FRUITS = [
+    "apple",
+<<<<<<< HEAD
+    "cherry",
+=======
+    "banana",
+>>>>>>> add-fruit
+    "mango",
+    "orange",
+]
+----
+
+Then you might edit that part of the code like this,
+which includes the fruits from both sides of the conflict:

+[[diff3]]

Documentation/gitmergeconflicts.adoc +21 -0

+DIFF3
+-----
+
+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`.
+This extra context can make it much easier to understand what's
+happening in a merge conflict.
+
+Here's an example of what a merge conflict would look like when using
+`diff3`. There's an extra section (between `|||||||` and `=======`)
+with the original code.
+
+With this view, you can see that both sides fixed a spelling
+mistake in "mango", and each added one fruit to the list.
+
+----
+FRUITS = [
+    "apple",
+<<<<<<< HEAD
+    "cherry",

+[NOTE]
+================================
+zdiff3 is an alternative to diff3 that makes the merge conflict +shorter by making it more ambiguous.
+================================

Quoted 7 lines · Julia Evans via GitGitGadget

From: Julia Evans <[email protected]>

Introduce a new page, gitmergeconflicts, that explains the process of handling a merge conflict in a way that addresses the following issues, which came from feedback from Git users on the current explanation of merge conflicts in the git merge man page:

Quoted 3 lines

- The process for resolving a merge conflict is only explained in the
...
- It sometimes uses the term "area" and sometimes uses the term "hunk"

It looks a bit annoying that these sentences in the enumeration all lack their full stops.