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:

 * [x] Explain what a merge conflict is (thanks to Junio & Ben)
 * [x] rewrite the "ours" vs "theirs" section (thanks to Patrick for the
   comments)
 * [x] add git log --merge (thanks to Ben)
 * [x] Leave most of the content of git cherry-pick as-is, to make this
   patch set smaller (thanks to Junio)
 * [x] remove the SYNOPSIS since hopefully that won't be required anymore by
   the time this is merged
 * [x] Fix a typo in git revert (s/reverted conflict/reverted commit/)
 * [x] 's/the the/the/' (thanks to Patrick)
 * [x] s/[doc] Thing/doc: thing/ in commit messages (thanks to Tuomas)'
 * [x] squash the commit fixing the linter error (thanks to Junio)
 * [x] list reviewers in Reviewed-by

Some things that we discussed but stayed the same:

 * "git commit does the same thing as git merge --continue" seems to be true
   so we can leave it
 * Don't involve git am and git apply in this.
 * Junio suggested another diff3 example but I feel like there are already a
   lot of examples
 * We've still removed one mention of MERGE_HEAD in the git merge man page
   without replacing it. It's mentioned in other places though.

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   |  11 +-
 Documentation/git-merge.adoc         | 125 +---------
 Documentation/git-pull.adoc          |   3 +-
 Documentation/git-rebase.adoc        |  13 +-
 Documentation/git-revert.adoc        |   5 +
 Documentation/gitmergeconflicts.adoc | 333 +++++++++++++++++++++++++++
 Documentation/meson.build            |   1 +
 command-list.txt                     |   1 +
 10 files changed, 362 insertions(+), 132 deletions(-)
 create mode 100644 Documentation/gitmergeconflicts.adoc

base-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7

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