[PATCH 0/7] [doc] Add new page on merge conflicts

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.

This is a pretty big change, so here's a list of things I'm still considering in the hopes that it'll help with the discussion:

 * I wrote that git commit does the same thing as git merge --continue
   during a git merge , but I'm not sure if that's always true.
 * Not 100% sure that the explanation of diff3 vs zdiff3 is correct
 * Right now we're listing git merge, git revert, git rebase, git
   cherry-pick, and git pull as commands that can cause merge conflicts. I
   believe that git apply and git am can also result in conflicts when
   applying a patch, though it's a bit complicated because applying a patch
   is a different operation than doing a 3-way merge and the tools available
   for dealing with it are a different. My thought right now is to avoid the
   issue of applying patches for now (because it's a whole can of worms) and
   instead just try to not imply that this is necessarily an exhaustive
   list. Also if/when the git rebase --squash changes land, then we'd need
   to add git history to this list.
 * Instead of creating a new page, I considered using an include to have a
   "handling merge conflicts" section in git rebase, git merge, etc. Merge
   conflict resolution is complex and it's very useful to be able to include
   examples: this version ended up at ~300 lines and I think that's too big
   of an include, especially for short man pages like cherry-pick
 * Explaining what "ours" and "theirs" mean was one of the hardest parts of
   writing this. From polling Git users in one of my many informal Mastodon
   polls about Git, my understanding is that Git users are actually
   relatively unlikely to actually reason about what "ours" and "theirs"
   mean when dealing with a merge conflict, and that most people prefer to
   get more context instead, for example by using a mergetool or by using
   diff3 or zdiff3. I heard a lot of "I can never remember which is which I
   so I don't even try". So I put the information about what "ours" and
   "theirs" mean relatively far down the page (with some cross-references),
   so that it's easily available but not the main focus.
 * I removed a couple of mentions of the various _HEAD references. It's hard
   for me to know exactly where they belong because I personally have never
   used MERGE_HEAD, REBASE_HEAD, ORIG_HEAD, CHERRY_PICK_HEAD etc, and I
   don't know how they're meant to be used. From some quick unscientific
   polling (at https://social.jvns.ca/@b0rk/117320011885941855), it seems
   like most Git users have never used them either (and folks who do use a
   *_HEAD reference mainly seem to use FETCH_HEAD which isn't relevant
   here), so from that perspective it seems important to avoid emphasizing
   them too much. The git revert man page doesn't mention REVERT_HEAD and
   git rebase only mentions REBASE_HEAD in passing. Of course they're all
   explained in gitrevisions(7) which might be the best place for them.
 * I'm still not sure what the SYNOPSIS section is for in a "guide" man page
   which is not about a specific Git command (what is the user intended to
   use it for?). I tried to leave it out but the CI said it was required.

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 (7):
  [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
  [doc] ignore conflict markers in gitmergeconflicts.adoc

 .gitattributes                       |   1 +
 Documentation/Makefile               |   1 +
 Documentation/git-cherry-pick.adoc   |  23 +--
 Documentation/git-merge.adoc         | 125 +-----------
 Documentation/git-pull.adoc          |   3 +-
 Documentation/git-rebase.adoc        |  13 +-
 Documentation/git-revert.adoc        |   5 +
 Documentation/gitmergeconflicts.adoc | 294 +++++++++++++++++++++++++++
 Documentation/meson.build            |   1 +
 9 files changed, 320 insertions(+), 146 deletions(-)
 create mode 100644 Documentation/gitmergeconflicts.adoc

base-commit: 3bc0341126508f78f5869cbfc0005e987efdf0c7
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-2237%2Fjvns%2Fmerge-conflicts-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-2237/jvns/merge-conflicts-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/2237