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

Re: [PATCH v4 0/6] [doc] Add new page on merge conflicts

From
Ben Knoble <ben.knoble@gmail.com>
Date
Oct 23, 2026, 14:18 UTC
Message-ID
<254688CB-AD21-4283-AE19-F1061C90C6B3@gmail.com>
In-Reply-To
<pull.2237.v4.git.1792764293.gitgitgadget@gmail.com>
Show 87 quoted lines
> Le 23 oct. 2026 à 10:04, Julia Evans via GitGitGadget <gitgitgadget@gmail.com> a écrit :
> 
> 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.
> 
> Changed in v2:
> 
> * Explain what a merge conflict is (thanks to Junio & Ben)
> * rewrite the "ours" vs "theirs" section (thanks to Patrick for the
>   comments)
> * add git log --merge (thanks to Ben)
> * Leave most of the content of git cherry-pick as-is, to make this patch
>   set smaller (thanks to Junio)
> * remove the SYNOPSIS since hopefully that won't be required anymore by the
>   time this is merged
> * Fix a typo in git revert (s/reverted conflict/reverted commit/)
> * 's/the the/the/' (thanks to Patrick)
> * s/[doc] Thing/doc: thing/ in commit messages (thanks to Tuomas)'
> * squash the commit fixing the linter error (thanks to Junio)
> * list reviewers in Reviewed-by
> 
> Changed in v3:
> 
> Thanks to all the comments from Junio.
> 
> * Add signoff from Marie
> * In "For example, here's a merge conflict where both sides edited a list
>   of", add a little more detail about how to interpret the merge conflict
> * When we introduce a merge mention "semantic merge conflicts"
> * Say "... and any other command that does a merge" when listing commands
>   that can cause merge conflicts.
> * Reviewed-by is not the right thing, use Helped-by
> * Adjust phrasing in git revert and git cherry-pick man pages
> * Reference the "ours" section in "git show :2:filename shows the "ours""
> * "there's one file left with conflicts in it: fruits.py" isn't precise
>   enough, instead say "the conflicts in fruits.py haven't been marked as
>   resolved"
> * Delete the explanation of zdiff3 and add a brief warning instead. Don't
>   be too prescriptive, we should tell people what the issue is (ambiguity)
>   instead of trying to impose our opinion.
> * Explain ||||||| when we add diff3
> * Fix example in "EXAMPLE OF RESOLVING A MERGE CONFLICT" to make it
>   consistent with the other examples
> * Replace "configuration option" with "configuration variable"
> * Mention --skip instead of saying "the most common ways", which is
>   ambiguous
> * Add a pointer to the extended AUTO_MERGE sentence
> 
> Changed in v4:
> 
> changes to the content:
> 
> * use Junio's much better example for diff3
> * clarify in the commit message why we're not mentioning git apply: to
>   avoid dealing with patches (thanks to Junio)
> * adjust the wording around "multi-step operation like a rebase" (thanks to
>   Junio)
> * Say "see git-config for more" in the description of zdiff3. Like Patrick
>   said the explanation of zdiff3 is not really satisfiying, but I don't
>   know how to write a satisfying explanation, and it's better to have a
>   short and obviously unsatisfying explanation than a long unsatisfying
>   one. Added a note in the commit message that perhaps this should be
>   improved in the future. (from Patrick's comment)
> 
> changes cleaning things up:
> 
> * add periods at the ends of various sentences in an attempt to be more
>   consistent (thanks to Junio & Patrick)
> * Adjust the formatting around the [NOTE] to make the CI whitespace check
>   pass
> * Replace a couple of instances of "code" with "lines" (thanks to Junio)
> * Fix Ben's email address (thanks to Ben)
> * Remove the double signoff (thanks to Ben).
> * Make the cherry-pick commit message more accurate (thanks to Patrick)
> 
> Thanks to Lobo, Adam Svahn, Louis Vanier, David Turner, Ben Zanin, Salih,
> and about 12 others who gave feedback on both the original git merge man
> page, as well as the proposed improvements.

I’m happy with this version based on the range-diff, and I suspect we are reaching the point of diminishing returns.

Previous: Julia Evans via GitGitGadgetNext: Junio C Hamano
Message 99 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.