From: Ben Knoble Date: Fri, 23 Oct 2026 14:18:54 GMT Subject: Re: [PATCH v4 0/6] [doc] Add new page on merge conflicts Message-ID: <254688CB-AD21-4283-AE19-F1061C90C6B3@gmail.com> In-Reply-To: > Le 23 oct. 2026 à 10:04, Julia Evans via GitGitGadget 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.