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

From: Philippe Blain via GitGitGadget <gitgitgadget@gmail.com>
Date: May 22, 2023, 19:28 UTC
Message-ID: <pull.1515.v2.git.1684783741.gitgitgadget@gmail.com>
In-Reply-To: <pull.1515.git.1681495119.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