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
Patrick Steinhardt <ps@pks.im>
Date
Oct 13, 2026, 11:07 UTC
Message-ID
<as4RAcQxknZXcBVd@pks.im>
In-Reply-To
<7aa0ae7ec3c1d02aa1533c27fa40f4815c03ba6e.1791816795.git.gitgitgadget@gmail.com>
On Mon, Oct 12, 2026 at 02:53:10PM +0000, Julia Evans via GitGitGadget wrote:
Show 31 quoted lines
> diff --git a/Documentation/gitmergeconflicts.adoc b/Documentation/gitmergeconflicts.adoc
> new file mode 100644
> index 0000000000..3c6eaaddf8
> --- /dev/null
> +++ b/Documentation/gitmergeconflicts.adoc
> @@ -0,0 +1,330 @@
> +gitmergeconflicts(7)
> +====================
> +
> +NAME
> +----
> +gitmergeconflicts - Guide to handling merge conflicts
> +
> +DESCRIPTION
> +-----------
> +
> +Merge conflicts can happen during a `git merge`, `git rebase`, `git
> +cherry-pick`, `git pull`, `git revert`, or any other command that does
> +a merge. All of those commands use the same merge algorithm, and the
> +process for resolving a merge conflict is always very similar.
> +
> +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
Nit: the punctuation is a bit inconsistent, where the second bullet
point has a trailing punctuation mark but the other two don't.
Show 20 quoted 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
> +the same file, then it can easily combine them since there's no overlap.
> +
> +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.
Same nit here.
Show 7 quoted lines
> +[NOTE]
> +================================
> +Even if Git successfully merges both sides with no conflicts, it's
> +possible to end up with code that doesn't work. For example, this can
> +happen if one side renames a function, and the other side adds a call to
> +the old function. This is called a "semantic merge conflict".
> +================================

Good callout. We may also want to spell out the consequence of this: "You should always verify the result of a merge regardless of whether or not it has resulted in a conflict.".

Show 15 quoted lines
> +[[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.

Same nit regarding punctuation. Or is this actually a thing, where you add punctuation in case it's multiple sentences but not in the case where it's a single sentence, only? Maybe this is just me not being a native speaker.

Show 16 quoted lines
> +[[tools]]
> +TOOLS FOR HANDLING MERGE CONFLICTS
> +----------------------------------
> +
> +Here are some ways to get extra context while handling a merge conflict:
> +
> +* There are many graphical "merge tools" for Git, which will normally
> +  show you the different versions of the code side by side.
> +  If you have a mergetool configured, `git mergetool` will launch it.
> +  See also `merge.tool` in linkgit:git-config[1] for a list of
> +  the mergetools Git supports.
> +
> +* You can set the configuration variable `merge.conflictstyle=diff3`.
> +  See <<diff3,DIFF3>> below for more.
> +
> +* `git log --merge -p <filename>`  will list all commits which

Should we spell this out as `--patch` instead? That's way easier to grep in the manpage in case the reader is curious what the option does.

Show 5 quoted lines
> +[NOTE]
> +================================
> +`zdiff3` is an alternative to `diff3` that makes the merge conflict
> +shorter by making it more ambiguous.
> +================================

"making it more ambiguous" reads rather curious. Should we maybe take inspiration from its documentation and instead say "by removing matching lines on the two sides from the beginning or end of a conflict region"?

Show 10 quoted lines
> +[[ours]]
> +"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.

They may not always be commits, but they are always tree-ishs. But I think it's fine to leave this as-is anyway, as the normal user is never going to encounter cases where it's not in fact a commit. And when they do they probably don't need this manpage anyway.

Other than this handful of nits I'm happy with this version, thanks!
Patrick
Previous: Junio C HamanoNext: Julia Evans
Message 75 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.