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

[Ben Knoble <ben.knoble@gmail.com>]

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