[PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs

["Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com>]

Thanks everyone for the review!

Changes since v1:

 * Addressed typos and wording suggestions from Elijah
 * Incoporated Eric's wording suggestion
 * Added a preliminary patch adressing Victoria's suggestion, based on the
   what Taylor sent.

This version is not a "fixups on top", it's a complete new version. I don't
see the point of merging typos to master if we can instead wait for 'next'
to be rebuilt after the upcoming release.

v1: This series adds documentation (and completion!) for AUTO_MERGE. In
doing so I noticed that some other special refs where not mentioned in
'gitrevisions' nor suggested by the completion, so I also tried to improve
that.

Since the changes are in the same parts of the same files, I thought it made
more sense to send everything in the same series to avoid conflicts, but I
can send the AUTO_MERGE patches on top of the other ones in a separate
series if that would be preferred.

Here is a breakdown of the patches. First the "other special refs" patches:

 * [PATCH 1/5] revisions.txt: document more special refs
 * [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD

Then a preparatory cleanup for the AUTO_MERGE patches:

 * [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section

Finally the AUTO_MERGE patches:

 * [PATCH 4/5] Documentation: document AUTO_MERGE
 * [PATCH 5/5] completion: complete AUTO_MERGE

Thanks Elijah for this very useful feature! Dscho, I'm CC-ing you since you
opened https://github.com/gitgitgadget/git/issues/1471, I hope that's OK.

Cheers,

Philippe.

Philippe Blain (6):
  revisions.txt: use description list for special refs
  revisions.txt: document more special refs
  completion: complete REVERT_HEAD and BISECT_HEAD
  git-merge.txt: modernize word choice in "True merge" section
  Documentation: document AUTO_MERGE
  completion: complete AUTO_MERGE

 Documentation/git-diff.txt             |  9 ++++-
 Documentation/git-merge.txt            | 11 ++++--
 Documentation/revisions.txt            | 50 ++++++++++++++++++--------
 Documentation/user-manual.txt          | 27 ++++++++++++++
 contrib/completion/git-completion.bash |  2 +-
 5 files changed, 79 insertions(+), 20 deletions(-)


base-commit: a0f05f684010332ab3a706979d191b9157643f80
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1515%2Fphil-blain%2Fdoc-auto-merge-v2
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1515/phil-blain/doc-auto-merge-v2
Pull-Request: https://github.com/gitgitgadget/git/pull/1515

Range-diff vs v1:

 -:  ----------- > 1:  1bacd52a432 revisions.txt: use description list for special refs
 1:  66c7e514157 ! 2:  3e3240a78f8 revisions.txt: document more special refs
     @@ Commit message
       ## Documentation/revisions.txt ##
      @@ Documentation/revisions.txt: characters and to avoid word splitting.
         first match in the following rules:
     - 
     + +
         . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually
      -    useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`
      -    and `CHERRY_PICK_HEAD`);
     @@ Documentation/revisions.txt: characters and to avoid word splitting.
       
         . otherwise, 'refs/<refname>' if it exists;
       
     -@@ Documentation/revisions.txt: you can easily change the tip of the branch back to the state before you ran
     - them.
     - `MERGE_HEAD` records the commit(s) which you are merging into your branch
     - when you run `git merge`.
     -+`REBASE_HEAD`, during a rebase, records the commit at which the
     -+operation is currently stopped, either because of conflicts or an `edit`
     -+command in an interactive rebase.
     -+`REVERT_HEAD` records the commit which you are reverting when you
     -+run `git revert`.
     - `CHERRY_PICK_HEAD` records the commit which you are cherry-picking
     - when you run `git cherry-pick`.
     -+`BISECT_HEAD` records the current commit to be tested when you
     -+run `git bisect --no-checkout`.
     +@@ Documentation/revisions.txt: characters and to avoid word splitting.
     +   `MERGE_HEAD`:::
     +     records the commit(s) which you are merging into your branch when you
     +     run `git merge`.
     ++  `REBASE_HEAD`:::
     ++    during a rebase, records the commit at which the operation is
     ++    currently stopped, either because of conflicts or an `edit` command in
     ++    an interactive rebase.
     ++  `REVERT_HEAD`:::
     ++    records the commit which you are reverting when you run `git revert`.
     +   `CHERRY_PICK_HEAD`:::
     +     records the commit which you are cherry-picking when you run `git
     +     cherry-pick`.
     ++  `BISECT_HEAD`:::
     ++    records the current commit to be tested when you run `git bisect
     ++    --no-checkout`.
     + 
       +
       Note that any of the 'refs/*' cases above may come either from
     - the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
 2:  f3a47758f9d = 3:  70487d66459 completion: complete REVERT_HEAD and BISECT_HEAD
 3:  62b68829c5a ! 4:  f1d99453f54 git-merge.txt: modernize word choice in "True merge" section
     @@ Commit message
      
          The "True merge" section of the 'git merge' documentation mentions that
          in case of conflicts, the conflicted working tree files contain "the
     -    result of the "merge" program". This probably refers to RCS' 'merge'
     +    result of the "merge" program". This probably refers to RCS's 'merge'
          program, which is mentioned further down under "How conflicts are
          presented".
      
 4:  0cdd4ab3d73 ! 5:  612073d9508 Documentation: document AUTO_MERGE
     @@ Commit message
      
          In git-merge(1), add a step to the list of things that happen "when it
          is not obvious how to reconcile the changes", under the "True merge"
     -    secion. Also mention AUTO_MERGE in the "How to resolve conflicts"
     +    section. Also mention AUTO_MERGE in the "How to resolve conflicts"
          section, when mentioning 'git diff'.
      
          In gitrevisions(7), add a mention of AUTO_MERGE along with the other
     @@ Documentation/git-diff.txt: If --merge-base is given, use the merge base of the
      +by the special ref `AUTO_MERGE`, which is written by the 'ort' merge
      +strategy upon hitting merge conflicts (see linkgit:git-merge[1]).
      +Comparing the working tree with `AUTO_MERGE` shows changes you've made
     -+so far to resolve conflicts (see the examples below).
     ++so far to resolve textual conflicts (see the examples below).
       
       For a more complete list of ways to spell <commit>, see
       "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
     @@ Documentation/git-diff.txt: $ git diff HEAD       <3>
           would be committing if you run `git commit` without `-a` option.
       <3> Changes in the working tree since your last commit; what you
           would be committing if you run `git commit -a`
     -+<4> Changes in the working tree you've made to resolve conflicts so far.
     ++<4> Changes in the working tree you've made to resolve textual
     ++    conflicts so far.
       
       Comparing with arbitrary commits::
       +
     @@ Documentation/git-merge.txt: happens:
          tree files contain the result of the merge operation; i.e. 3-way
          merge results with familiar conflict markers `<<<` `===` `>>>`.
      -5. No other changes are made.  In particular, the local
     -+5. A special ref `AUTO_MERGE` is written, pointing to a tree corresponding
     -+   to the current content of the working tree (including conflict markers).
     -+   Note that this ref is only written when the 'ort' merge strategy
     -+   is used (the default).
     ++5. A special ref `AUTO_MERGE` is written, pointing to a tree
     ++   corresponding to the current content of the working tree (including
     ++   conflict markers for textual conflicts).  Note that this ref is only
     ++   written when the 'ort' merge strategy is used (the default).
      +6. No other changes are made.  In particular, the local
          modifications you had before you started merge will stay the
          same and the index entries for them stay as they were,
     @@ Documentation/git-merge.txt: You can work through the conflict with a number of
          highlighting changes from both the `HEAD` and `MERGE_HEAD`
      -   versions.
      +   versions. `git diff AUTO_MERGE` will show what changes you've
     -+   made so far to resolve conlicts.
     ++   made so far to resolve textual conflicts.
       
        * Look at the diffs from each branch. `git log --merge -p <path>`
          will show diffs first for the `HEAD` version and then the
      
       ## Documentation/revisions.txt ##
      @@ Documentation/revisions.txt: characters and to avoid word splitting.
     - 
     + +
         . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually
           useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`,
      -    `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`);
     @@ Documentation/revisions.txt: characters and to avoid word splitting.
       
         . otherwise, 'refs/<refname>' if it exists;
       
     -@@ Documentation/revisions.txt: run `git revert`.
     - when you run `git cherry-pick`.
     - `BISECT_HEAD` records the current commit to be tested when you
     - run `git bisect --no-checkout`.
     -+`AUTO_MERGE` records a tree object corresponding to the state the
     -+'ort' merge strategy wrote to the working tree when a merge operation
     -+resulted in conflicts.
     +@@ Documentation/revisions.txt: characters and to avoid word splitting.
     +   `BISECT_HEAD`:::
     +     records the current commit to be tested when you run `git bisect
     +     --no-checkout`.
     ++  `AUTO_MERGE`:::
     ++    records a tree object corresponding to the state the
     ++    'ort' merge strategy wrote to the working tree when a merge operation
     ++    resulted in conflicts.
     + 
       +
       Note that any of the 'refs/*' cases above may come either from
     - the `$GIT_DIR/refs` directory or from the `$GIT_DIR/packed-refs` file.
      
       ## Documentation/user-manual.txt ##
      @@ Documentation/user-manual.txt: $ git diff -3 file.txt		# diff against stage 3
     @@ Documentation/user-manual.txt: $ git diff -3 file.txt		# diff against stage 3
       
      +When using the 'ort' merge strategy (the default), before updating the working
      +tree with the result of the merge, Git writes a special ref named AUTO_MERGE
     -+reflecting the state of the tree it is about to write. Conflicted paths that
     -+could not be automatically merged are written to this tree with conflict
     -+markers, just as in the working tree. AUTO_MERGE can thus be used with
     -+linkgit:git-diff[1] to show the changes you've made so far to resolve
     ++reflecting the state of the tree it is about to write. Conflicted paths with
     ++textual conflicts that could not be automatically merged are written to this
     ++tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be
     ++used with linkgit:git-diff[1] to show the changes you've made so far to resolve
      +conflicts. Using the same example as above, after resolving the conflict we
      +get:
      +
     @@ -1,5 +1 @@
      ++Goodbye world
      +-------------------------------------------------
      +
     -+Notice that the diff shows we deleted the conflict markers and both versions,
     -+and wrote "Goodbye world" instead.
     ++Notice that the diff shows we deleted the conflict markers and both versions of
     ++the content line, and wrote "Goodbye world" instead.
      +
       The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
       for merges:
 5:  88cc7a80f31 = 6:  17226c56e7b completion: complete AUTO_MERGE

-- 
gitgitgadget