git/list[1] front-page[2] threads[3] people[4] search[5] about
 

Re: [PATCH v3 1/6] doc: add new gitmergeconflicts man page

From
Julia Evans <julia@jvns.ca>
Date
Oct 14, 2026, 19:24 UTC
Message-ID
<89df0444-1447-4267-9e28-bc4dc70b0478@app.fastmail.com>
In-Reply-To
<xmqqwlrm7pii.fsf@gitster.g>
On Mon, Oct 12, 2026, at 2:16 PM, Junio C Hamano wrote:
Show 15 quoted lines
> "Julia Evans via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
>> From: Julia Evans <julia@jvns.ca>
>>
>> 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"
>
> It looks a bit annoying that these sentences in the enumeration all
> lack their full stops.
Sure, will fix.
Show 6 quoted lines
>> 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`.
>
> I do not know "because it's awkward" is a good justification,
> though.  "awkward" why?

It's because `apply` and `am` can also apply patches, and that's a whole separate topic than explaining the 3-way merge. I think explaining the difference between applying a patch and doing a 3-way merge could be interesting to do in the future but this is already quite a big patch series.

Show 27 quoted lines
> It might be tempting to omit some commands that are less common for
> new users, but we are touching the main part of the technical manual
> that are meant ot be used by everybody, so that is not a good reason
> to choose covering some but not others.
>
> I however agree that it is better to avoid appearing to be complete
> and leaving others (including future ones we add) with "any other
> command that does a merge" as this round of document gives.
>
>> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
>> ...
>> +There are 3 ways to handle a merge conflict:
>> +
>> +* Resolve the conflict. (see <<resolve,HOW TO RESOLVE A MERGE CONFLICT>>
>> +  below for details)
>> +* 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.
>> +* Or (if you're in a multi-step rebase or cherry-pick) skip the problematic
>> +  commit with the appropriate `--skip` command
>
> The third entry is a nice addition.  multi-step anything are the
> same, including revert, right?  I'd recommend updating it to
> something like "if you are in a multi-step operation like `rebase`"
> in the same spirit as the "or any other command" change you made at
> the beginning of this file.
Done.
Show 11 quoted lines
>> +When there's a merge conflict, 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 -- one side added "cherry" and the other side
>> +added "banana":
>
> You added "-- one side added ..." at the end, which I think sends a
> wrong message.  With rcs-merge style conflict, you cannot simply
> tell, because it is ambiguous.  The original may have had both
> banana and cherry, in which case the sample output shows the result
> of one side removing banana and the other side removing cherry.
Make sense, will replace "added" with "has".
Show 59 quoted lines
>> +[[diff3]]
>> +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",
>> +    "mango",
>> +||||||| 1c22e48
>> +    "mangoooo",
>> +=======
>> +    "banana",
>> +    "mango",
>> +>>>>>>> add-fruit
>> +    "orange",
>> +]
>> +----
>
> THis is a great example.  
>
> But an even better example would be to give this:
>
>         FRUITS = [
>             "apple",
>         <<<<<<< HEAD
>             "cherry",
>             "mango",
>         ||||||| 1c22e48
>             "banana",
>             "cherry",
>             "mangoooo",
>         =======
>             "banana",
>             "mango",
>         >>>>>>> add-fruit
>             "orange",
>         ]
>
> and tell the readers that that the correct resolution is to have
> "apply, mango, orange", as each of cherry and banana was removed by
> one side while the other side did not touch it.  Having cherry and
> banana in the result is a tempting but not always correct conclusion
> unexperienced people would draw from the rcs-merge style output that
> is ambiguous, and here is a great place to teach it in this flow.
Thanks, this is a much better example, for the reasons you say. Will use it.

I always appreciate thinking carefully about which examples to give, it's so important.

Show 21 quoted lines
> Especially because it would make it stand out that the point of
> diff3's verboseness compared to the rcs-merge output is to
> disambiguate two cases.  If you start from ABCmO and one side has
> ABMO while the other side has ACMO, the right resolution would be
> AMO (the above case I added), but if your starting point were AmO
> and the two sides ends with ABMO and ACMO respectively, the right
> resolution would be ABCMO.  The rcs-merge output does not tell you
> which is more likely to be correct, diff3 disambiguates these two
> cases by being more verbose.
>
> And telling that value of diff3 is about disambiguating is valuable
> when ...
>
>> +[NOTE]
>> +================================
>> +`zdiff3` is an alternative to `diff3` that makes the merge conflict
>> +shorter by making it more ambiguous.
>> +================================
>
> ... this note tells the readers that zdiff3 is a ambigous variant of
> diff3, hinting its flaw.
Previous: Junio C HamanoNext: Junio C Hamano
Message 73 of 109 in “[doc] Add new page on merge conflicts”
  1. 0/7 [doc] Add new page on merge conflictsJulia Evans via GitGitGadget, Sep 24, 2026
  2. 1/7 [doc] Add new gitmergeconflicts man pageJulia Evans via GitGitGadget, Sep 24, 2026
  3. Junio C HamanoSep 24, 2026
  4. Junio C HamanoSep 24, 2026
  5. Patrick SteinhardtSep 30, 2026
  6. Julia EvansSep 30, 2026
  7. Junio C HamanoSep 30, 2026
  8. Patrick SteinhardtOct 1, 2026
  9. Julia EvansOct 1, 2026
  10. Junio C HamanoOct 2, 2026
  11. Julia EvansOct 5, 2026
  12. Junio C HamanoOct 5, 2026
  13. Julia EvansOct 5, 2026
  14. 2/7 [doc] git-merge: link to new merge conflicts guideJulia Evans via GitGitGadget, Sep 24, 2026
  15. D. Ben KnobleSep 25, 2026
  16. Julia EvansSep 25, 2026
  17. Junio C HamanoSep 25, 2026
  18. Ben KnobleSep 25, 2026
  19. Junio C HamanoSep 25, 2026
  20. Ben KnobleSep 25, 2026
  21. Julia EvansOct 2, 2026
  22. Junio C HamanoOct 2, 2026
  23. Julia EvansOct 2, 2026
  24. Junio C HamanoOct 2, 2026
  25. D. Ben KnobleOct 3, 2026
  26. Junio C HamanoOct 3, 2026
  27. Patrick SteinhardtSep 30, 2026
  28. 3/7 [doc] git-rebase: link to new merge conflicts guideJulia Evans via GitGitGadget, Sep 24, 2026
  29. 4/7 [doc] git-revert: link to new merge conflicts guideJulia Evans via GitGitGadget, Sep 24, 2026
  30. 5/7 [doc] git-cherry-pick: link to new merge conflicts guideJulia Evans via GitGitGadget, Sep 24, 2026
  31. Junio C HamanoSep 25, 2026
  32. Julia EvansSep 28, 2026
  33. Junio C HamanoSep 28, 2026
  34. 6/7 [doc] git-pull: link to new merge conflicts guideJulia Evans via GitGitGadget, Sep 24, 2026
  35. 7/7 [doc] ignore conflict markers in gitmergeconflicts.adocJulia Evans via GitGitGadget, Sep 24, 2026
  36. Junio C HamanoOct 7, 2026
  37. Julia EvansOct 9, 2026
  38. Junio C HamanoSep 24, 2026
  39. Jeff KingSep 24, 2026
  40. Julia EvansSep 28, 2026
  41. Jeff KingSep 29, 2026
  42. Junio C HamanoSep 29, 2026
  43. D. Ben KnobleSep 25, 2026
  44. Julia EvansOct 2, 2026
  45. D. Ben KnobleOct 3, 2026
  46. Julia EvansOct 5, 2026
  47. D. Ben KnobleOct 6, 2026
  48. D. Ben KnobleOct 6, 2026
  49. 0/6 [doc] Add new page on merge conflictsJulia Evans via GitGitGadget, Oct 9, 2026
  50. 1/6 doc: add new gitmergeconflicts man pageJulia Evans via GitGitGadget, Oct 9, 2026
  51. Junio C HamanoOct 9, 2026
  52. Julia EvansOct 9, 2026
  53. Junio C HamanoOct 9, 2026
  54. Junio C HamanoOct 10, 2026
  55. 2/6 doc: git-merge: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 9, 2026
  56. Junio C HamanoOct 9, 2026
  57. 3/6 doc: git-rebase: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 9, 2026
  58. Junio C HamanoOct 9, 2026
  59. 4/6 doc: git-revert: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 9, 2026
  60. Junio C HamanoOct 9, 2026
  61. 5/6 doc: git-cherry-pick: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 9, 2026
  62. Junio C HamanoOct 9, 2026
  63. Julia EvansOct 9, 2026
  64. 6/6 doc: git-pull: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 9, 2026
  65. Junio C HamanoOct 9, 2026
  66. Junio C HamanoOct 9, 2026
  67. Julia EvansOct 9, 2026
  68. Ben KnobleOct 9, 2026
  69. Junio C HamanoOct 9, 2026
  70. 0/6 [doc] Add new page on merge conflictsJulia Evans via GitGitGadget, Oct 12, 2026
  71. 1/6 doc: add new gitmergeconflicts man pageJulia Evans via GitGitGadget, Oct 12, 2026
  72. Junio C HamanoOct 12, 2026
  73. Julia EvansOct 14, 2026
  74. Junio C HamanoOct 14, 2026
  75. Patrick SteinhardtOct 13, 2026
  76. Julia EvansOct 14, 2026
  77. 2/6 doc: git-merge: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 12, 2026
  78. 3/6 doc: git-rebase: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 12, 2026
  79. 4/6 doc: git-revert: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 12, 2026
  80. 5/6 doc: git-cherry-pick: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 12, 2026
  81. Patrick SteinhardtOct 13, 2026
  82. 6/6 doc: git-pull: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 12, 2026
  83. D. Ben KnobleOct 12, 2026
  84. Julia EvansOct 12, 2026
  85. Junio C HamanoOct 12, 2026
  86. Junio C HamanoOct 12, 2026
  87. 0/6 [doc] Add new page on merge conflictsJulia Evans via GitGitGadget, Oct 23, 2026
  88. 1/6 doc: add new gitmergeconflicts man pageJulia Evans via GitGitGadget, Oct 23, 2026
  89. Junio C HamanoOct 23, 2026
  90. Julia EvansOct 26, 2026
  91. Junio C HamanoOct 26, 2026
  92. Julia EvansOct 26, 2026
  93. Junio C HamanoOct 26, 2026
  94. 2/6 doc: git-merge: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 23, 2026
  95. 3/6 doc: git-rebase: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 23, 2026
  96. 4/6 doc: git-revert: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 23, 2026
  97. 5/6 doc: git-cherry-pick: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 23, 2026
  98. 6/6 doc: git-pull: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 23, 2026
  99. Ben KnobleOct 23, 2026
  100. Junio C HamanoOct 23, 2026
  101. Junio C HamanoOct 23, 2026
  102. Junio C HamanoOct 23, 2026
  103. 0/6 [doc] Add new page on merge conflictsJulia Evans via GitGitGadget, Oct 26, 2026
  104. 1/6 doc: add new gitmergeconflicts man pageJulia Evans via GitGitGadget, Oct 26, 2026
  105. 2/6 doc: git-merge: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 26, 2026
  106. 3/6 doc: git-rebase: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 26, 2026
  107. 4/6 doc: git-revert: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 26, 2026
  108. 5/6 doc: git-cherry-pick: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 26, 2026
  109. 6/6 doc: git-pull: link to new merge conflicts guideJulia Evans via GitGitGadget, Oct 26, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.