Document 'AUTO_MERGE' and more special refs

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