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

some non-changes in v3:

 * didn't add any extra Reviewed-by
 * "return your branch to its original state": left the same because during
   a multistep cherry-pick the branch does need to be returned to its
   original state
 * leave the explanation of AUTO_MERGE the same since Marie says it's more
   clear this way
 * leave contractions alone for now
 * don't say semantic merge applies to all merges since I think that will be
   clear to readers
 * the wording of "When Git merges two commits together" is a bit weird but
   we don't have a better idea right now
 * don't explain --left-right. Can be very easily added in the future if we
   think it's important.

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.

Julia Evans (6):
  doc: add new gitmergeconflicts man page
  doc: git-merge: link to new merge conflicts guide
  doc: git-rebase: link to new merge conflicts guide
  doc: git-revert: link to new merge conflicts guide
  doc: git-cherry-pick: link to new merge conflicts guide
  doc: git-pull: link to new merge conflicts guide

 .gitattributes                       |   1 +
 Documentation/Makefile               |   1 +
 Documentation/git-cherry-pick.adoc   |   8 +-
 Documentation/git-merge.adoc         | 125 +---------
 Documentation/git-pull.adoc          |   3 +-
 Documentation/git-rebase.adoc        |  13 +-
 Documentation/git-revert.adoc        |   5 +
 Documentation/gitmergeconflicts.adoc | 330 +++++++++++++++++++++++++++
 Documentation/meson.build            |   1 +
 command-list.txt                     |   1 +
 10 files changed, 357 insertions(+), 131 deletions(-)
 create mode 100644 Documentation/gitmergeconflicts.adoc

base-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7

Submitted-As: https://lore.kernel.org/git/pull.2237.v3.git.1791816795.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.2237.git.1790261062.gitgitgadget@gmail.com
In-Reply-To: https://lore.kernel.org/git/pull.2237.v2.git.1791547213.gitgitgadget@gmail.com