* [PATCH 0/5] Document 'AUTO_MERGE' and more special refs
@ 2023-04-14 17:58 Philippe Blain via GitGitGadget
2023-04-14 17:58 ` [PATCH 1/5] revisions.txt: document " Philippe Blain via GitGitGadget
` (8 more replies)
0 siblings, 9 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-04-14 17:58 UTC (permalink / raw)
To: git; +Cc: Elijah Newren, Johannes Schindelin, Philippe Blain
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 (5):
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 | 8 +++++++-
Documentation/git-merge.txt | 11 ++++++++---
Documentation/revisions.txt | 15 ++++++++++++--
Documentation/user-manual.txt | 27 ++++++++++++++++++++++++++
contrib/completion/git-completion.bash | 2 +-
5 files changed, 56 insertions(+), 7 deletions(-)
base-commit: a0f05f684010332ab3a706979d191b9157643f80
Published-As: https://github.com/gitgitgadget/git/releases/tag/pr-1515%2Fphil-blain%2Fdoc-auto-merge-v1
Fetch-It-Via: git fetch https://github.com/gitgitgadget/git pr-1515/phil-blain/doc-auto-merge-v1
Pull-Request: https://github.com/gitgitgadget/git/pull/1515
--
gitgitgadget
^ permalink raw reply [flat|nested] 35+ messages in thread
* [PATCH 1/5] revisions.txt: document more special refs
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
@ 2023-04-14 17:58 ` Philippe Blain via GitGitGadget
2023-04-14 18:49 ` Junio C Hamano
2023-04-14 19:49 ` Victoria Dye
2023-04-14 17:58 ` [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD Philippe Blain via GitGitGadget
` (7 subsequent siblings)
8 siblings, 2 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-04-14 17:58 UTC (permalink / raw)
To: git; +Cc: Elijah Newren, Johannes Schindelin, Philippe Blain,
Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Some special refs, namely HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD and
CHERRY_PICK_HEAD, are mentioned and described in 'gitrevisions', but some
others, namely REBASE_HEAD, REVERT_HEAD, and BISECT_HEAD, are not.
Add a small description of these special refs.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/revisions.txt | 11 +++++++++--
1 file changed, 9 insertions(+), 2 deletions(-)
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 9aa58052bc7..98b8f89bc8d 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -32,8 +32,8 @@ 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`);
+ useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`,
+ `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`);
. otherwise, 'refs/<refname>' if it exists;
@@ -55,8 +55,15 @@ 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`.
+
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.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
2023-04-14 17:58 ` [PATCH 1/5] revisions.txt: document " Philippe Blain via GitGitGadget
@ 2023-04-14 17:58 ` Philippe Blain via GitGitGadget
2023-04-14 20:25 ` Junio C Hamano
2023-04-14 17:58 ` [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section Philippe Blain via GitGitGadget
` (6 subsequent siblings)
8 siblings, 1 reply; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-04-14 17:58 UTC (permalink / raw)
To: git; +Cc: Elijah Newren, Johannes Schindelin, Philippe Blain,
Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The pseudorefs REVERT_HEAD and BISECT_HEAD are not suggested
by the __git_refs function. Add them there.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
contrib/completion/git-completion.bash | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index dc95c34cc85..bcda376735c 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -767,7 +767,7 @@ __git_refs ()
track=""
;;
*)
- for i in HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD REBASE_HEAD CHERRY_PICK_HEAD; do
+ for i in HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD REBASE_HEAD CHERRY_PICK_HEAD REVERT_HEAD BISECT_HEAD; do
case "$i" in
$match*|$umatch*)
if [ -e "$dir/$i" ]; then
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
2023-04-14 17:58 ` [PATCH 1/5] revisions.txt: document " Philippe Blain via GitGitGadget
2023-04-14 17:58 ` [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD Philippe Blain via GitGitGadget
@ 2023-04-14 17:58 ` Philippe Blain via GitGitGadget
2023-04-14 20:36 ` Junio C Hamano
2023-04-14 17:58 ` [PATCH 4/5] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
` (5 subsequent siblings)
8 siblings, 1 reply; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-04-14 17:58 UTC (permalink / raw)
To: git; +Cc: Elijah Newren, Johannes Schindelin, Philippe Blain,
Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
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'
program, which is mentioned further down under "How conflicts are
presented".
Since it is not clear at that point of the document which program is
referred to, and since most modern readers probably do not relate to RCS
anyway, let's just write "the merge operation" instead.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-merge.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 0aeff572a59..23aefe28851 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -194,7 +194,7 @@ happens:
versions: stage 1 stores the version from the common ancestor,
stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
can inspect the stages with `git ls-files -u`). The working
- tree files contain the result of the "merge" program; i.e. 3-way
+ 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
modifications you had before you started merge will stay the
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* [PATCH 4/5] Documentation: document AUTO_MERGE
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
` (2 preceding siblings ...)
2023-04-14 17:58 ` [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section Philippe Blain via GitGitGadget
@ 2023-04-14 17:58 ` Philippe Blain via GitGitGadget
2023-04-14 21:41 ` Taylor Blau
` (2 more replies)
2023-04-14 17:58 ` [PATCH 5/5] completion: complete AUTO_MERGE Philippe Blain via GitGitGadget
` (4 subsequent siblings)
8 siblings, 3 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-04-14 17:58 UTC (permalink / raw)
To: git; +Cc: Elijah Newren, Johannes Schindelin, Philippe Blain,
Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Since 5291828df8 (merge-ort: write $GIT_DIR/AUTO_MERGE whenever we hit a
conflict, 2021-03-20), when using the 'ort' merge strategy, the special
ref AUTO_MERGE is written when a merge operation results in conflicts.
This ref points to a tree recording the conflicted state of the working
tree and is very useful during conflict resolution. However, this ref is
not documented.
Add some documentation for AUTO_MERGE in git-diff(1), git-merge(1),
gitrevisions(7) and in the user manual.
In git-diff(1), mention it at the end of the description section, when
we mention that the command also accepts trees instead of commits, and
also add an invocation to the "Various ways to check your working tree"
example.
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, when mentioning 'git diff'.
In gitrevisions(7), add a mention of AUTO_MERGE along with the other
special refs.
In the user manual, add a paragraph describing AUTO_MERGE to the
"Getting conflict-resolution help during a merge" section, and include
an example of a 'git diff AUTO_MERGE' invocation for the example
conflict used in that section. Note that for uniformity we do not use
backticks around AUTO_MERGE here since the rest of the document does not
typeset special refs differently.
Closes: https://github.com/gitgitgadget/git/issues/1471
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-diff.txt | 8 +++++++-
Documentation/git-merge.txt | 9 +++++++--
Documentation/revisions.txt | 6 +++++-
Documentation/user-manual.txt | 27 +++++++++++++++++++++++++++
4 files changed, 46 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 52b679256c4..a85cc756ebc 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -102,7 +102,11 @@ If --merge-base is given, use the merge base of the two commits for the
Just in case you are doing something exotic, it should be
noted that all of the <commit> in the above description, except
in the `--merge-base` case and in the last two forms that use `..`
-notations, can be any <tree>.
+notations, can be any <tree>. A tree of interest is the one pointed to
+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).
For a more complete list of ways to spell <commit>, see
"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
@@ -152,6 +156,7 @@ Various ways to check your working tree::
$ git diff <1>
$ git diff --cached <2>
$ git diff HEAD <3>
+$ git diff AUTO_MERGE <4>
------------
+
<1> Changes in the working tree not yet staged for the next commit.
@@ -159,6 +164,7 @@ $ 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.
Comparing with arbitrary commits::
+
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 23aefe28851..3f61389c1c2 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -196,7 +196,11 @@ happens:
can inspect the stages with `git ls-files -u`). The working
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).
+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,
i.e. matching `HEAD`.
@@ -336,7 +340,8 @@ You can work through the conflict with a number of tools:
* Look at the diffs. `git diff` will show a three-way diff,
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.
* Look at the diffs from each branch. `git log --merge -p <path>`
will show diffs first for the `HEAD` version and then the
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 98b8f89bc8d..b42a2bb30a5 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -33,7 +33,8 @@ 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`);
+ `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD`, `BISECT_HEAD`
+ and `AUTO_MERGE`);
. otherwise, 'refs/<refname>' if it exists;
@@ -64,6 +65,9 @@ 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.
+
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.
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index dc9c6a663a9..99e5f652e92 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1343,6 +1343,33 @@ $ git diff -3 file.txt # diff against stage 3
$ git diff --theirs file.txt # same as the above.
-------------------------------------------------
+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
+conflicts. Using the same example as above, after resolving the conflict we
+get:
+
+-------------------------------------------------
+$ git diff AUTO_MERGE
+diff --git a/file.txt b/file.txt
+index cd10406..8bf5ae7 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1,5 +1 @@
+-<<<<<<< HEAD:file.txt
+-Hello world
+-=======
+-Goodbye
+->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
++Goodbye world
+-------------------------------------------------
+
+Notice that the diff shows we deleted the conflict markers and both versions,
+and wrote "Goodbye world" instead.
+
The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
for merges:
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* [PATCH 5/5] completion: complete AUTO_MERGE
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
` (3 preceding siblings ...)
2023-04-14 17:58 ` [PATCH 4/5] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
@ 2023-04-14 17:58 ` Philippe Blain via GitGitGadget
2023-04-14 18:34 ` [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Junio C Hamano
` (3 subsequent siblings)
8 siblings, 0 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-04-14 17:58 UTC (permalink / raw)
To: git; +Cc: Elijah Newren, Johannes Schindelin, Philippe Blain,
Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The pseudoref AUTO_MERGE is documented since the previous commit. To
make it easier to use, let __git_refs in the Bash completion code
complete it.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
contrib/completion/git-completion.bash | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index bcda376735c..945d2543b07 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -767,7 +767,7 @@ __git_refs ()
track=""
;;
*)
- for i in HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD REBASE_HEAD CHERRY_PICK_HEAD REVERT_HEAD BISECT_HEAD; do
+ for i in HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD REBASE_HEAD CHERRY_PICK_HEAD REVERT_HEAD BISECT_HEAD AUTO_MERGE; do
case "$i" in
$match*|$umatch*)
if [ -e "$dir/$i" ]; then
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* Re: [PATCH 0/5] Document 'AUTO_MERGE' and more special refs
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
` (4 preceding siblings ...)
2023-04-14 17:58 ` [PATCH 5/5] completion: complete AUTO_MERGE Philippe Blain via GitGitGadget
@ 2023-04-14 18:34 ` Junio C Hamano
2023-04-14 19:49 ` Victoria Dye
` (2 subsequent siblings)
8 siblings, 0 replies; 35+ messages in thread
From: Junio C Hamano @ 2023-04-14 18:34 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Elijah Newren, Johannes Schindelin, Philippe Blain
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> This series adds documentation (and completion!) for AUTO_MERGE.
Nice. It indeed is one of the hard-to-discover gems.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 1/5] revisions.txt: document more special refs
2023-04-14 17:58 ` [PATCH 1/5] revisions.txt: document " Philippe Blain via GitGitGadget
@ 2023-04-14 18:49 ` Junio C Hamano
2023-04-15 5:18 ` Felipe Contreras
2023-04-14 19:49 ` Victoria Dye
1 sibling, 1 reply; 35+ messages in thread
From: Junio C Hamano @ 2023-04-14 18:49 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Elijah Newren, Johannes Schindelin, Philippe Blain
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> Some special refs, namely HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD and
> CHERRY_PICK_HEAD, are mentioned and described in 'gitrevisions', but some
> others, namely REBASE_HEAD, REVERT_HEAD, and BISECT_HEAD, are not.
>
> Add a small description of these special refs.
>
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---
> Documentation/revisions.txt | 11 +++++++++--
> 1 file changed, 9 insertions(+), 2 deletions(-)
>
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 9aa58052bc7..98b8f89bc8d 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -32,8 +32,8 @@ 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`);
> + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`,
> + `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`);
Adding missing ones and enumerating them indeed is good, but I
wonder if the readers will be helped if they are exposed to the
phrase "pseudoref" here.
This is usually useful only for the pseudorefs, i.e. `HEAD`,
`FETCH_HEAD`, ..."
We have definition of it in the glossary, but it does not have an
exhaustive list (and if we want to have an exhausitive list on this
page, the glossary definition of pseudoref may want to point at this
page).
It is an unrelated tangent that shouldn't be added to the
documentation (yet), but didn't we have a plan to limit the
pseudorefs to those names that end with "_HEAD"?
> +`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.
OK.
> +`REVERT_HEAD` records the commit which you are reverting when you
> +run `git revert`.
OK.
> +`BISECT_HEAD` records the current commit to be tested when you
> +run `git bisect --no-checkout`.
OK.
Looking very good.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 1/5] revisions.txt: document more special refs
2023-04-14 17:58 ` [PATCH 1/5] revisions.txt: document " Philippe Blain via GitGitGadget
2023-04-14 18:49 ` Junio C Hamano
@ 2023-04-14 19:49 ` Victoria Dye
2023-04-14 21:14 ` Taylor Blau
1 sibling, 1 reply; 35+ messages in thread
From: Victoria Dye @ 2023-04-14 19:49 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget, git
Cc: Elijah Newren, Johannes Schindelin, Philippe Blain
Philippe Blain via GitGitGadget wrote:
> @@ -55,8 +55,15 @@ 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`.
This is a fairly minor point, so feel free to ignore if you disagree or feel
it's not worth the effort:
Although the special refs in this list (HEAD, MERGE_HEAD, REBASE_HEAD etc.)
are visually separated by newlines in this doc, they render in the manpages
& HTML in a single monolithic paragraph (see [1]). With the addition of
three more descriptions (four if you count 'AUTO_MERGE' in patch 4/5), that
paragraph is getting large enough that it might be difficult for a reader to
parse and find information about a specific ref.
To help with that, you could create visual separation in the rendered doc by
adding a '+' between each special ref description; converting them into a
bullet pointed list would also work, I think.
[1] https://git-scm.com/docs/revisions#Documentation/revisions.txt-emltrefnamegtemegemmasterememheadsmasterememrefsheadsmasterem
> +
> 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.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 0/5] Document 'AUTO_MERGE' and more special refs
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
` (5 preceding siblings ...)
2023-04-14 18:34 ` [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Junio C Hamano
@ 2023-04-14 19:49 ` Victoria Dye
2023-04-15 7:09 ` Elijah Newren
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
8 siblings, 0 replies; 35+ messages in thread
From: Victoria Dye @ 2023-04-14 19:49 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget, git
Cc: Elijah Newren, Johannes Schindelin, Philippe Blain
Philippe Blain via GitGitGadget wrote:
> 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.
The documentation you've added is clear without being too verbose (the
AUTO_MERGE description & example in patch 4 are especially helpful), the
completion changes are a nice quality-of-life improvement, and the patches
are well-organized. Aside from one minor (and entirely optional) suggestion
in patch 1, everything in this series looks great to me. Thank you for
making these changes!
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD
2023-04-14 17:58 ` [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD Philippe Blain via GitGitGadget
@ 2023-04-14 20:25 ` Junio C Hamano
0 siblings, 0 replies; 35+ messages in thread
From: Junio C Hamano @ 2023-04-14 20:25 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Elijah Newren, Johannes Schindelin, Philippe Blain
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> The pseudorefs REVERT_HEAD and BISECT_HEAD are not suggested
> by the __git_refs function. Add them there.
>
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---
> contrib/completion/git-completion.bash | 2 +-
> 1 file changed, 1 insertion(+), 1 deletion(-)
>
> diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
> index dc95c34cc85..bcda376735c 100644
> --- a/contrib/completion/git-completion.bash
> +++ b/contrib/completion/git-completion.bash
> @@ -767,7 +767,7 @@ __git_refs ()
> track=""
> ;;
> *)
> - for i in HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD REBASE_HEAD CHERRY_PICK_HEAD; do
> + for i in HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD REBASE_HEAD CHERRY_PICK_HEAD REVERT_HEAD BISECT_HEAD; do
> case "$i" in
> $match*|$umatch*)
> if [ -e "$dir/$i" ]; then
This does obvious change to add two completion possibilities reusing
exactly the same logic we have been using.
A tangent related to my earlier "didn't we plan to limit them to
*_HEAD at some point?" is that we could turn the loop around and do
something like
for i in HEAD $(cd "$dir" && echo *_HEAD)
do
case "$i" in
$match*|$umatch*)
if test -f "$dir/$i"
then
...
which could be a lot more future-proof, once we have such a rule.
But that is a tangent that we should wait until the current series
settles.
Thanks.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section
2023-04-14 17:58 ` [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section Philippe Blain via GitGitGadget
@ 2023-04-14 20:36 ` Junio C Hamano
0 siblings, 0 replies; 35+ messages in thread
From: Junio C Hamano @ 2023-04-14 20:36 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Elijah Newren, Johannes Schindelin, Philippe Blain
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> 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'
> program, which is mentioned further down under "How conflicts are
> presented".
>
> Since it is not clear at that point of the document which program is
> referred to, and since most modern readers probably do not relate to RCS
> anyway, let's just write "the merge operation" instead.
Good.
I suspect that the original refers literally to the RCS's merge
program. Until caba139d (Use git-merge-file in git-merge-one-file,
too, 2006-12-22) switched to use our poor-man's substitute for
"merge", we used to invoke "merge" for three-way merge.
We no longer do, and a more generic "merge operation" is certainly a
lot more appropriate in today's world.
> can inspect the stages with `git ls-files -u`). The working
> - tree files contain the result of the "merge" program; i.e. 3-way
> + tree files contain the result of the merge operation; i.e. 3-way
> merge results with familiar conflict markers `<<<` `===` `>>>`.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 1/5] revisions.txt: document more special refs
2023-04-14 19:49 ` Victoria Dye
@ 2023-04-14 21:14 ` Taylor Blau
2023-04-15 5:35 ` Felipe Contreras
0 siblings, 1 reply; 35+ messages in thread
From: Taylor Blau @ 2023-04-14 21:14 UTC (permalink / raw)
To: Victoria Dye
Cc: Philippe Blain via GitGitGadget, git, Elijah Newren,
Johannes Schindelin, Philippe Blain
On Fri, Apr 14, 2023 at 12:49:16PM -0700, Victoria Dye wrote:
> To help with that, you could create visual separation in the rendered doc by
> adding a '+' between each special ref description; converting them into a
> bullet pointed list would also work, I think.
In case you're looking for another option, you could convert these into
a description list, which would be consistent with the outer-most list
in this document.
I had to refresh myself on how the spacing and continuations work in
ASCIIdoc, but I think the following (which applies on top of this patch)
is right:
--- 8< ---
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 98b8f89bc8..b34f981622 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -30,7 +30,7 @@ characters and to avoid word splitting.
explicitly say 'heads/master' to tell Git which one you mean.
When ambiguous, a '<refname>' is disambiguated by taking the
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`,
`REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`);
@@ -44,26 +44,34 @@ characters and to avoid word splitting.
. otherwise, 'refs/remotes/<refname>' if it exists;
. otherwise, 'refs/remotes/<refname>/HEAD' if it exists.
+
+
-`HEAD` names the commit on which you based the changes in the working tree.
-`FETCH_HEAD` records the branch which you fetched from a remote repository
-with your last `git fetch` invocation.
-`ORIG_HEAD` is created by commands that move your `HEAD` in a drastic
-way (`git am`, `git merge`, `git rebase`, `git reset`),
-to record the position of the `HEAD` before their operation, so that
-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`.
+ `HEAD`:::
+ names the commit on which you based the changes in the working tree.
+ `FETCH_HEAD`:::
+ records the branch which you fetched from a remote repository with
+ your last `git fetch` invocation.
+ `ORIG_HEAD`:::
+ is created by commands that move your `HEAD` in a drastic way (`git
+ am`, `git merge`, `git rebase`, `git reset`), to record the position
+ of the `HEAD` before their operation, so that 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`.
+
+
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.
--- >8 ---
Thanks,
Taylor
^ permalink raw reply related [flat|nested] 35+ messages in thread
* Re: [PATCH 4/5] Documentation: document AUTO_MERGE
2023-04-14 17:58 ` [PATCH 4/5] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
@ 2023-04-14 21:41 ` Taylor Blau
2023-04-15 5:08 ` Eric Sunshine
2023-04-15 7:03 ` Elijah Newren
2 siblings, 0 replies; 35+ messages in thread
From: Taylor Blau @ 2023-04-14 21:41 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Elijah Newren, Johannes Schindelin, Philippe Blain
On Fri, Apr 14, 2023 at 05:58:37PM +0000, Philippe Blain via GitGitGadget wrote:
> Closes: https://github.com/gitgitgadget/git/issues/1471
Neat. This does close the corresponding issue once the result gets
pushed back to gitgitgadget/git. TIL!
> ---
> Documentation/git-diff.txt | 8 +++++++-
> Documentation/git-merge.txt | 9 +++++++--
> Documentation/revisions.txt | 6 +++++-
> Documentation/user-manual.txt | 27 +++++++++++++++++++++++++++
> 4 files changed, 46 insertions(+), 4 deletions(-)
These changes all look great to me, well written and explained.
Thanks,
Taylor
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 4/5] Documentation: document AUTO_MERGE
2023-04-14 17:58 ` [PATCH 4/5] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
2023-04-14 21:41 ` Taylor Blau
@ 2023-04-15 5:08 ` Eric Sunshine
2023-04-15 7:08 ` Elijah Newren
2023-04-15 7:03 ` Elijah Newren
2 siblings, 1 reply; 35+ messages in thread
From: Eric Sunshine @ 2023-04-15 5:08 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Elijah Newren, Johannes Schindelin, Philippe Blain
On Fri, Apr 14, 2023 at 2:13 PM Philippe Blain via GitGitGadget
<gitgitgadget@gmail.com> wrote:
> Add some documentation for AUTO_MERGE in git-diff(1), git-merge(1),
> gitrevisions(7) and in the user manual.
>
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> @@ -1343,6 +1343,33 @@ $ git diff -3 file.txt # diff against stage 3
> +-------------------------------------------------
> +$ git diff AUTO_MERGE
> +diff --git a/file.txt b/file.txt
> +index cd10406..8bf5ae7 100644
> +--- a/file.txt
> ++++ b/file.txt
> +@@ -1,5 +1 @@
> +-<<<<<<< HEAD:file.txt
> +-Hello world
> +-=======
> +-Goodbye
> +->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
> ++Goodbye world
> +-------------------------------------------------
> +
> +Notice that the diff shows we deleted the conflict markers and both versions,
> +and wrote "Goodbye world" instead.
Some grammatical problem here. Perhaps s/and both/in both/, or maybe
just drop "and both versions"?
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 1/5] revisions.txt: document more special refs
2023-04-14 18:49 ` Junio C Hamano
@ 2023-04-15 5:18 ` Felipe Contreras
0 siblings, 0 replies; 35+ messages in thread
From: Felipe Contreras @ 2023-04-15 5:18 UTC (permalink / raw)
To: Junio C Hamano, Philippe Blain via GitGitGadget
Cc: git, Elijah Newren, Johannes Schindelin, Philippe Blain
Junio C Hamano wrote:
> "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
>
> > From: Philippe Blain <levraiphilippeblain@gmail.com>
> >
> > Some special refs, namely HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD and
> > CHERRY_PICK_HEAD, are mentioned and described in 'gitrevisions', but some
> > others, namely REBASE_HEAD, REVERT_HEAD, and BISECT_HEAD, are not.
> >
> > Add a small description of these special refs.
> >
> > Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> > ---
> > Documentation/revisions.txt | 11 +++++++++--
> > 1 file changed, 9 insertions(+), 2 deletions(-)
> >
> > diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> > index 9aa58052bc7..98b8f89bc8d 100644
> > --- a/Documentation/revisions.txt
> > +++ b/Documentation/revisions.txt
> > @@ -32,8 +32,8 @@ 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`);
> > + useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`,
> > + `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`);
>
> Adding missing ones and enumerating them indeed is good, but I
> wonder if the readers will be helped if they are exposed to the
> phrase "pseudoref" here.
First time I've heard that term.
> This is usually useful only for the pseudorefs, i.e. `HEAD`,
> `FETCH_HEAD`, ..."
Isn't `HEAD` supposed to be a "symbolic ref"?
It definitely seems some explanation is missing.
--
Felipe Contreras
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 1/5] revisions.txt: document more special refs
2023-04-14 21:14 ` Taylor Blau
@ 2023-04-15 5:35 ` Felipe Contreras
0 siblings, 0 replies; 35+ messages in thread
From: Felipe Contreras @ 2023-04-15 5:35 UTC (permalink / raw)
To: Taylor Blau, Victoria Dye
Cc: Philippe Blain via GitGitGadget, git, Elijah Newren,
Johannes Schindelin, Philippe Blain
Taylor Blau wrote:
> On Fri, Apr 14, 2023 at 12:49:16PM -0700, Victoria Dye wrote:
> > To help with that, you could create visual separation in the rendered doc by
> > adding a '+' between each special ref description; converting them into a
> > bullet pointed list would also work, I think.
>
> In case you're looking for another option, you could convert these into
> a description list, which would be consistent with the outer-most list
> in this document.
>
> I had to refresh myself on how the spacing and continuations work in
> ASCIIdoc, but I think the following (which applies on top of this patch)
> is right:
Fortunately it's easy to test:
asciidoctor - <<\EOF >foo.html
`HEAD`:::
names the commit on which you based the changes in the working tree.
`FETCH_HEAD`:::
records the branch which you fetched from a remote repository with
your last `git fetch` invocation.
EOF
Yes, the format is fine, I'd just use `::` instead of `:::` as that's generally
the first level, but in practical terms doesn't really matter.
https://docs.asciidoctor.org/asciidoc/latest/lists/description/
Cheers.
--
Felipe Contreras
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 4/5] Documentation: document AUTO_MERGE
2023-04-14 17:58 ` [PATCH 4/5] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
2023-04-14 21:41 ` Taylor Blau
2023-04-15 5:08 ` Eric Sunshine
@ 2023-04-15 7:03 ` Elijah Newren
2023-04-15 15:36 ` Philippe Blain
2 siblings, 1 reply; 35+ messages in thread
From: Elijah Newren @ 2023-04-15 7:03 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget; +Cc: git, Johannes Schindelin, Philippe Blain
On Fri, Apr 14, 2023 at 10:58 AM Philippe Blain via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> From: Philippe Blain <levraiphilippeblain@gmail.com>
>
> Since 5291828df8 (merge-ort: write $GIT_DIR/AUTO_MERGE whenever we hit a
> conflict, 2021-03-20), when using the 'ort' merge strategy, the special
> ref AUTO_MERGE is written when a merge operation results in conflicts.
> This ref points to a tree recording the conflicted state of the working
> tree and is very useful during conflict resolution. However, this ref is
> not documented.
>
> Add some documentation for AUTO_MERGE in git-diff(1), git-merge(1),
> gitrevisions(7) and in the user manual.
>
> In git-diff(1), mention it at the end of the description section, when
> we mention that the command also accepts trees instead of commits, and
> also add an invocation to the "Various ways to check your working tree"
> example.
>
> 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"
s/secion/section/
> section, when mentioning 'git diff'.
>
> In gitrevisions(7), add a mention of AUTO_MERGE along with the other
> special refs.
>
> In the user manual, add a paragraph describing AUTO_MERGE to the
> "Getting conflict-resolution help during a merge" section, and include
> an example of a 'git diff AUTO_MERGE' invocation for the example
> conflict used in that section. Note that for uniformity we do not use
> backticks around AUTO_MERGE here since the rest of the document does not
> typeset special refs differently.
>
> Closes: https://github.com/gitgitgadget/git/issues/1471
> Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> ---
> Documentation/git-diff.txt | 8 +++++++-
> Documentation/git-merge.txt | 9 +++++++--
> Documentation/revisions.txt | 6 +++++-
> Documentation/user-manual.txt | 27 +++++++++++++++++++++++++++
> 4 files changed, 46 insertions(+), 4 deletions(-)
>
> diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
> index 52b679256c4..a85cc756ebc 100644
> --- a/Documentation/git-diff.txt
> +++ b/Documentation/git-diff.txt
> @@ -102,7 +102,11 @@ If --merge-base is given, use the merge base of the two commits for the
> Just in case you are doing something exotic, it should be
> noted that all of the <commit> in the above description, except
> in the `--merge-base` case and in the last two forms that use `..`
> -notations, can be any <tree>.
> +notations, can be any <tree>. A tree of interest is the one pointed to
> +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).
>
> For a more complete list of ways to spell <commit>, see
> "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
> @@ -152,6 +156,7 @@ Various ways to check your working tree::
> $ git diff <1>
> $ git diff --cached <2>
> $ git diff HEAD <3>
> +$ git diff AUTO_MERGE <4>
> ------------
> +
> <1> Changes in the working tree not yet staged for the next commit.
> @@ -159,6 +164,7 @@ $ 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.
>
> Comparing with arbitrary commits::
> +
> diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
> index 23aefe28851..3f61389c1c2 100644
> --- a/Documentation/git-merge.txt
> +++ b/Documentation/git-merge.txt
> @@ -196,7 +196,11 @@ happens:
> can inspect the stages with `git ls-files -u`). The working
> 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).
> +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,
> i.e. matching `HEAD`.
> @@ -336,7 +340,8 @@ You can work through the conflict with a number of tools:
>
> * Look at the diffs. `git diff` will show a three-way diff,
> 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.
s/conlicts/conflicts/
>
> * Look at the diffs from each branch. `git log --merge -p <path>`
> will show diffs first for the `HEAD` version and then the
> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
> index 98b8f89bc8d..b42a2bb30a5 100644
> --- a/Documentation/revisions.txt
> +++ b/Documentation/revisions.txt
> @@ -33,7 +33,8 @@ 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`);
> + `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD`, `BISECT_HEAD`
> + and `AUTO_MERGE`);
>
> . otherwise, 'refs/<refname>' if it exists;
>
> @@ -64,6 +65,9 @@ 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.
> +
> 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.
> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> index dc9c6a663a9..99e5f652e92 100644
> --- a/Documentation/user-manual.txt
> +++ b/Documentation/user-manual.txt
> @@ -1343,6 +1343,33 @@ $ git diff -3 file.txt # diff against stage 3
> $ git diff --theirs file.txt # same as the above.
> -------------------------------------------------
>
> +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
> +conflicts. Using the same example as above, after resolving the conflict we
> +get:
Mostly... To clarify, conflicted paths *with a textual conflict* are
written with conflict markers. Conflicted paths with non-textual
conflicts are not. There are several conflict types that fall into
the non-textual conflict umbrella: binary files, file/directory,
symlink/directory, symlink/file, modify/delete, rename/add,
rename/delete, rename/rename (1to2), and various submodule and
directory rename conflict types as well.
The AUTO_MERGE stuff will only help with seeing how textual conflicts
were resolved, it's not much help with the non-textual conflicts.
(By contrast, the closely related --remerge-diff option to `git log`
or `git show` does help see the resolution of *both* the textual and
non-textual conflicts, but of course one can't use that option on the
current merge until after first commiting the existing changes.)
> +
> +-------------------------------------------------
> +$ git diff AUTO_MERGE
> +diff --git a/file.txt b/file.txt
> +index cd10406..8bf5ae7 100644
> +--- a/file.txt
> ++++ b/file.txt
> +@@ -1,5 +1 @@
> +-<<<<<<< HEAD:file.txt
> +-Hello world
> +-=======
> +-Goodbye
> +->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
> ++Goodbye world
> +-------------------------------------------------
> +
> +Notice that the diff shows we deleted the conflict markers and both versions,
> +and wrote "Goodbye world" instead.
> +
> The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
> for merges:
>
> --
> gitgitgadget
>
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 4/5] Documentation: document AUTO_MERGE
2023-04-15 5:08 ` Eric Sunshine
@ 2023-04-15 7:08 ` Elijah Newren
2023-04-15 8:55 ` Eric Sunshine
0 siblings, 1 reply; 35+ messages in thread
From: Elijah Newren @ 2023-04-15 7:08 UTC (permalink / raw)
To: Eric Sunshine
Cc: Philippe Blain via GitGitGadget, git, Johannes Schindelin,
Philippe Blain
On Fri, Apr 14, 2023 at 10:08 PM Eric Sunshine <sunshine@sunshineco.com> wrote:
>
> On Fri, Apr 14, 2023 at 2:13 PM Philippe Blain via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
> > Add some documentation for AUTO_MERGE in git-diff(1), git-merge(1),
> > gitrevisions(7) and in the user manual.
> >
> > Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
> > ---
> > diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
> > @@ -1343,6 +1343,33 @@ $ git diff -3 file.txt # diff against stage 3
> > +-------------------------------------------------
> > +$ git diff AUTO_MERGE
> > +diff --git a/file.txt b/file.txt
> > +index cd10406..8bf5ae7 100644
> > +--- a/file.txt
> > ++++ b/file.txt
> > +@@ -1,5 +1 @@
> > +-<<<<<<< HEAD:file.txt
> > +-Hello world
> > +-=======
> > +-Goodbye
> > +->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
> > ++Goodbye world
> > +-------------------------------------------------
> > +
> > +Notice that the diff shows we deleted the conflict markers and both versions,
> > +and wrote "Goodbye world" instead.
>
> Some grammatical problem here. Perhaps s/and both/in both/, or maybe
> just drop "and both versions"?
It reads correctly as-is to me. There were five lines dropped:
* Three were lines starting with '<', '=', and '>' characters,
referred to as the conflict marker lines.
* Two were lines containing content from each of the sides ("Hello
world", and "Goodbye")
and one line added.
Thus, the diff shows we deleted the conflict markers (the 1st, 3rd and
5th lines) and both versions (lines 2 and 4), and wrote "Goodbye
world" instead.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 0/5] Document 'AUTO_MERGE' and more special refs
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
` (6 preceding siblings ...)
2023-04-14 19:49 ` Victoria Dye
@ 2023-04-15 7:09 ` Elijah Newren
2023-04-16 10:26 ` Chris Torek
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
8 siblings, 1 reply; 35+ messages in thread
From: Elijah Newren @ 2023-04-15 7:09 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget; +Cc: git, Johannes Schindelin, Philippe Blain
On Fri, Apr 14, 2023 at 10:58 AM Philippe Blain via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> 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.
Sweet, thanks for sending this in. I like the little touches you
added such as 3/5,
and fixing up docs of other refs.
I found a couple typos and some slightly misleading text in 4/5.
I'm also curious if it'd be worth attempting to point out the link
between AUTO_MERGE and the --remerge-diff flag to `git log` and `git
show`, though even if it is, it could always be added after this
series.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 4/5] Documentation: document AUTO_MERGE
2023-04-15 7:08 ` Elijah Newren
@ 2023-04-15 8:55 ` Eric Sunshine
2023-04-16 3:05 ` Elijah Newren
0 siblings, 1 reply; 35+ messages in thread
From: Eric Sunshine @ 2023-04-15 8:55 UTC (permalink / raw)
To: Elijah Newren
Cc: Philippe Blain via GitGitGadget, git, Johannes Schindelin,
Philippe Blain
On Sat, Apr 15, 2023 at 3:08 AM Elijah Newren <newren@gmail.com> wrote:
> On Fri, Apr 14, 2023 at 10:08 PM Eric Sunshine <sunshine@sunshineco.com> wrote:
> > On Fri, Apr 14, 2023 at 2:13 PM Philippe Blain via GitGitGadget
> > <gitgitgadget@gmail.com> wrote:
> > > +Notice that the diff shows we deleted the conflict markers and both versions,
> > > +and wrote "Goodbye world" instead.
> >
> > Some grammatical problem here. Perhaps s/and both/in both/, or maybe
> > just drop "and both versions"?
>
> It reads correctly as-is to me. There were five lines dropped:
> * Three were lines starting with '<', '=', and '>' characters,
> referred to as the conflict marker lines.
> * Two were lines containing content from each of the sides ("Hello
> world", and "Goodbye")
> and one line added.
>
> Thus, the diff shows we deleted the conflict markers (the 1st, 3rd and
> 5th lines) and both versions (lines 2 and 4), and wrote "Goodbye
> world" instead.
Yes, upon rereading it, I can interpret it in the way it was intended.
On my initial read-through, it sounded wrong. Perhaps, had it said
"and both versions of the content line" or such, it wouldn't have
tripped me up.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 4/5] Documentation: document AUTO_MERGE
2023-04-15 7:03 ` Elijah Newren
@ 2023-04-15 15:36 ` Philippe Blain
2023-04-15 23:31 ` Elijah Newren
0 siblings, 1 reply; 35+ messages in thread
From: Philippe Blain @ 2023-04-15 15:36 UTC (permalink / raw)
To: Elijah Newren, Philippe Blain via GitGitGadget; +Cc: git, Johannes Schindelin
Hi Elijah,
Le 2023-04-15 à 03:03, Elijah Newren a écrit :
> On Fri, Apr 14, 2023 at 10:58 AM Philippe Blain via GitGitGadget
> <gitgitgadget@gmail.com> wrote:
>>
Thanks for pointing out my typos, those are fixed.
>> diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
>> index dc9c6a663a9..99e5f652e92 100644
>> --- a/Documentation/user-manual.txt
>> +++ b/Documentation/user-manual.txt
>> @@ -1343,6 +1343,33 @@ $ git diff -3 file.txt # diff against stage 3
>> $ git diff --theirs file.txt # same as the above.
>> -------------------------------------------------
>>
>> +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
>> +conflicts. Using the same example as above, after resolving the conflict we
>> +get:
>
> Mostly... To clarify, conflicted paths *with a textual conflict* are
> written with conflict markers. Conflicted paths with non-textual
> conflicts are not. There are several conflict types that fall into
> the non-textual conflict umbrella: binary files, file/directory,
> symlink/directory, symlink/file, modify/delete, rename/add,
> rename/delete, rename/rename (1to2), and various submodule and
> directory rename conflict types as well.
>
> The AUTO_MERGE stuff will only help with seeing how textual conflicts
> were resolved, it's not much help with the non-textual conflicts.
That's true. I think that it might be a good idea to be explicit about
"textual conflicts". Although, I think that precision should also be made
in the other parts of the doc, not just the user manual, so I'll do that.
Thanks,
Philippe.
> (By contrast, the closely related --remerge-diff option to `git log`
> or `git show` does help see the resolution of *both* the textual and
> non-textual conflicts, but of course one can't use that option on the
> current merge until after first commiting the existing changes.)
That's true. And, remerge-diff only helps when actually looking at two-way
merge commit, not with conflicts hit during a rebase, cherry-pick or revert.
A semi-related trick I use to check conflict resolution during a rebase (after
resolving the conflicts but before 'git rebase --continue') is to manually
construct a commit from the index and use 'git range-diff' to compare it
to REBASE_HEAD. Thinking out loud, maybe a '--check-resolution' flag to the
sequencer would make sense to do that automatically...
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 4/5] Documentation: document AUTO_MERGE
2023-04-15 15:36 ` Philippe Blain
@ 2023-04-15 23:31 ` Elijah Newren
0 siblings, 0 replies; 35+ messages in thread
From: Elijah Newren @ 2023-04-15 23:31 UTC (permalink / raw)
To: Philippe Blain; +Cc: Philippe Blain via GitGitGadget, git, Johannes Schindelin
On Sat, Apr 15, 2023 at 8:36 AM Philippe Blain
<levraiphilippeblain@gmail.com> wrote:
>
> Hi Elijah,
>
<snip>
> > (By contrast, the closely related --remerge-diff option to `git log`
> > or `git show` does help see the resolution of *both* the textual and
> > non-textual conflicts, but of course one can't use that option on the
> > current merge until after first commiting the existing changes.)
>
> That's true. And, remerge-diff only helps when actually looking at two-way
> merge commit, not with conflicts hit during a rebase, cherry-pick or revert.
Good point. I have a small patchset to create an option allowing
folks to see how conflicts were resolved in reverts, and in
cherry-picks made with the -x option. I made it over two years ago,
but never ended up deciding whether to submit it or not. At some
point I put it up on gitgitgadget, at
https://github.com/gitgitgadget/git/pull/1151.
Points against it are that it doesn't work for rebases (because we
don't know which commits they were taken from) or for many
cherry-picks. Given the lower utility, and the fact that it involves
commit message scraping (looking for "reverts commit <X>" and
"(cherry-picked from <X>)"), I never ended up pushing for it.
> A semi-related trick I use to check conflict resolution during a rebase (after
> resolving the conflicts but before 'git rebase --continue') is to manually
> construct a commit from the index and use 'git range-diff' to compare it
> to REBASE_HEAD.
Heh, I have a semi-related trick as well. During rebases, when I want
to compare overall diffs for the current commit against what it was
picked from, I tend to use:
mydiff <(git log -1 -p REBASE_HEAD) <(git diff HEAD)
where `mydiff` is a specialized wrapper around `git diff --no-index`
that actually reads the contents of /dev/fd/<value> instead of
treating it as a symlink. (Though if I don't have that script handy,
I just plug in `diff -u` for `mydiff`).
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 4/5] Documentation: document AUTO_MERGE
2023-04-15 8:55 ` Eric Sunshine
@ 2023-04-16 3:05 ` Elijah Newren
0 siblings, 0 replies; 35+ messages in thread
From: Elijah Newren @ 2023-04-16 3:05 UTC (permalink / raw)
To: Eric Sunshine
Cc: Philippe Blain via GitGitGadget, git, Johannes Schindelin,
Philippe Blain
On Sat, Apr 15, 2023 at 1:55 AM Eric Sunshine <sunshine@sunshineco.com> wrote:
>
> On Sat, Apr 15, 2023 at 3:08 AM Elijah Newren <newren@gmail.com> wrote:
> > On Fri, Apr 14, 2023 at 10:08 PM Eric Sunshine <sunshine@sunshineco.com> wrote:
> > > On Fri, Apr 14, 2023 at 2:13 PM Philippe Blain via GitGitGadget
> > > <gitgitgadget@gmail.com> wrote:
> > > > +Notice that the diff shows we deleted the conflict markers and both versions,
> > > > +and wrote "Goodbye world" instead.
> > >
> > > Some grammatical problem here. Perhaps s/and both/in both/, or maybe
> > > just drop "and both versions"?
> >
> > It reads correctly as-is to me. There were five lines dropped:
> > * Three were lines starting with '<', '=', and '>' characters,
> > referred to as the conflict marker lines.
> > * Two were lines containing content from each of the sides ("Hello
> > world", and "Goodbye")
> > and one line added.
> >
> > Thus, the diff shows we deleted the conflict markers (the 1st, 3rd and
> > 5th lines) and both versions (lines 2 and 4), and wrote "Goodbye
> > world" instead.
>
> Yes, upon rereading it, I can interpret it in the way it was intended.
> On my initial read-through, it sounded wrong. Perhaps, had it said
> "and both versions of the content line" or such, it wouldn't have
> tripped me up.
That suggestion reads well to me too.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH 0/5] Document 'AUTO_MERGE' and more special refs
2023-04-15 7:09 ` Elijah Newren
@ 2023-04-16 10:26 ` Chris Torek
0 siblings, 0 replies; 35+ messages in thread
From: Chris Torek @ 2023-04-16 10:26 UTC (permalink / raw)
To: Elijah Newren
Cc: Philippe Blain via GitGitGadget, git, Johannes Schindelin,
Philippe Blain
I wonder if it's worth mentioning that these pseudo-refs
are really per-work-tree. A few too many add-ons to Git
forget to take this into consideration...
Chris
^ permalink raw reply [flat|nested] 35+ messages in thread
* [PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
` (7 preceding siblings ...)
2023-04-15 7:09 ` Elijah Newren
@ 2023-05-22 19:28 ` Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 1/6] revisions.txt: use description list for " Philippe Blain via GitGitGadget
` (7 more replies)
8 siblings, 8 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-05-22 19:28 UTC (permalink / raw)
To: git
Cc: Elijah Newren, Johannes Schindelin, Victoria Dye, Taylor Blau,
Eric Sunshine, Felipe Contreras, Philippe Blain, Chris Torek,
Philippe Blain
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
^ permalink raw reply [flat|nested] 35+ messages in thread
* [PATCH v2 1/6] revisions.txt: use description list for special refs
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
@ 2023-05-22 19:28 ` Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 2/6] revisions.txt: document more " Philippe Blain via GitGitGadget
` (6 subsequent siblings)
7 siblings, 0 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-05-22 19:28 UTC (permalink / raw)
To: git
Cc: Elijah Newren, Johannes Schindelin, Victoria Dye, Taylor Blau,
Eric Sunshine, Felipe Contreras, Philippe Blain, Chris Torek,
Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The special refs listed in 'gitrevisions' (under the '<refname>' entry)
are on separate lines in the Asciidoc source, but end up as a single
continuous paragraph in the rendered documentation (see e.g. [1]). In
following commits we will mention additional special refs, so to improve
legibility, use a description list such that every entry appears on its
own line. Since we are already in a description list, use ':::' as the
term delimiter.
In order for the new description list to be aligned with the description
under the '<refname>' entry, instead of being aligned with the last
entry of the "in the following rules" nested list, use the "ancestor
list continuation" syntax [2], i.e., leave an empty line before the
continuation '+'. Do the same for the paragraph following the new
description list ("Note that any...").
While at it, also use a continuation '+' before the "in the following
rules" list, for correctness. The parser seems not to care here, but
it's best to keep the sources correct.
[1] https://git-scm.com/docs/gitrevisions#Documentation/gitrevisions.txt-emltrefnamegtemegemmasterememheadsmasterememrefsheadsmasterem
[2] https://docs.asciidoctor.org/asciidoc/latest/lists/continuation/#ancestor-list-continuation
Suggested-by: Victoria Dye <vdye@github.com>
Based-on-patch-by: Taylor Blau <me@ttaylorr.com>
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/revisions.txt | 32 +++++++++++++++++++-------------
1 file changed, 19 insertions(+), 13 deletions(-)
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index 9aa58052bc7..ab5b8cf880b 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -30,7 +30,7 @@ characters and to avoid word splitting.
explicitly say 'heads/master' to tell Git which one you mean.
When ambiguous, a '<refname>' is disambiguated by taking the
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`);
@@ -44,19 +44,25 @@ characters and to avoid word splitting.
. otherwise, 'refs/remotes/<refname>' if it exists;
. otherwise, 'refs/remotes/<refname>/HEAD' if it exists.
+
+
-`HEAD` names the commit on which you based the changes in the working tree.
-`FETCH_HEAD` records the branch which you fetched from a remote repository
-with your last `git fetch` invocation.
-`ORIG_HEAD` is created by commands that move your `HEAD` in a drastic
-way (`git am`, `git merge`, `git rebase`, `git reset`),
-to record the position of the `HEAD` before their operation, so that
-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`.
-`CHERRY_PICK_HEAD` records the commit which you are cherry-picking
-when you run `git cherry-pick`.
+ `HEAD`:::
+ names the commit on which you based the changes in the working tree.
+ `FETCH_HEAD`:::
+ records the branch which you fetched from a remote repository with
+ your last `git fetch` invocation.
+ `ORIG_HEAD`:::
+ is created by commands that move your `HEAD` in a drastic way (`git
+ am`, `git merge`, `git rebase`, `git reset`), to record the position
+ of the `HEAD` before their operation, so that 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`.
+ `CHERRY_PICK_HEAD`:::
+ records the commit which you are cherry-picking when you run `git
+ cherry-pick`.
+
+
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.
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* [PATCH v2 2/6] revisions.txt: document more special refs
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 1/6] revisions.txt: use description list for " Philippe Blain via GitGitGadget
@ 2023-05-22 19:28 ` Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 3/6] completion: complete REVERT_HEAD and BISECT_HEAD Philippe Blain via GitGitGadget
` (5 subsequent siblings)
7 siblings, 0 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-05-22 19:28 UTC (permalink / raw)
To: git
Cc: Elijah Newren, Johannes Schindelin, Victoria Dye, Taylor Blau,
Eric Sunshine, Felipe Contreras, Philippe Blain, Chris Torek,
Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Some special refs, namely HEAD, FETCH_HEAD, ORIG_HEAD, MERGE_HEAD and
CHERRY_PICK_HEAD, are mentioned and described in 'gitrevisions', but some
others, namely REBASE_HEAD, REVERT_HEAD, and BISECT_HEAD, are not.
Add a small description of these special refs.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/revisions.txt | 13 +++++++++++--
1 file changed, 11 insertions(+), 2 deletions(-)
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index ab5b8cf880b..b34f981622b 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -32,8 +32,8 @@ 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`);
+ useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`,
+ `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`);
. otherwise, 'refs/<refname>' if it exists;
@@ -59,9 +59,18 @@ 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
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* [PATCH v2 3/6] completion: complete REVERT_HEAD and BISECT_HEAD
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 1/6] revisions.txt: use description list for " Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 2/6] revisions.txt: document more " Philippe Blain via GitGitGadget
@ 2023-05-22 19:28 ` Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 4/6] git-merge.txt: modernize word choice in "True merge" section Philippe Blain via GitGitGadget
` (4 subsequent siblings)
7 siblings, 0 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-05-22 19:28 UTC (permalink / raw)
To: git
Cc: Elijah Newren, Johannes Schindelin, Victoria Dye, Taylor Blau,
Eric Sunshine, Felipe Contreras, Philippe Blain, Chris Torek,
Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The pseudorefs REVERT_HEAD and BISECT_HEAD are not suggested
by the __git_refs function. Add them there.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
contrib/completion/git-completion.bash | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index dc95c34cc85..bcda376735c 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -767,7 +767,7 @@ __git_refs ()
track=""
;;
*)
- for i in HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD REBASE_HEAD CHERRY_PICK_HEAD; do
+ for i in HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD REBASE_HEAD CHERRY_PICK_HEAD REVERT_HEAD BISECT_HEAD; do
case "$i" in
$match*|$umatch*)
if [ -e "$dir/$i" ]; then
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* [PATCH v2 4/6] git-merge.txt: modernize word choice in "True merge" section
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
` (2 preceding siblings ...)
2023-05-22 19:28 ` [PATCH v2 3/6] completion: complete REVERT_HEAD and BISECT_HEAD Philippe Blain via GitGitGadget
@ 2023-05-22 19:28 ` Philippe Blain via GitGitGadget
2023-05-22 19:29 ` [PATCH v2 5/6] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
` (3 subsequent siblings)
7 siblings, 0 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-05-22 19:28 UTC (permalink / raw)
To: git
Cc: Elijah Newren, Johannes Schindelin, Victoria Dye, Taylor Blau,
Eric Sunshine, Felipe Contreras, Philippe Blain, Chris Torek,
Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
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's 'merge'
program, which is mentioned further down under "How conflicts are
presented".
Since it is not clear at that point of the document which program is
referred to, and since most modern readers probably do not relate to RCS
anyway, let's just write "the merge operation" instead.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-merge.txt | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 0aeff572a59..23aefe28851 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -194,7 +194,7 @@ happens:
versions: stage 1 stores the version from the common ancestor,
stage 2 from `HEAD`, and stage 3 from `MERGE_HEAD` (you
can inspect the stages with `git ls-files -u`). The working
- tree files contain the result of the "merge" program; i.e. 3-way
+ 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
modifications you had before you started merge will stay the
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* [PATCH v2 5/6] Documentation: document AUTO_MERGE
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
` (3 preceding siblings ...)
2023-05-22 19:28 ` [PATCH v2 4/6] git-merge.txt: modernize word choice in "True merge" section Philippe Blain via GitGitGadget
@ 2023-05-22 19:29 ` Philippe Blain via GitGitGadget
2023-05-22 19:29 ` [PATCH v2 6/6] completion: complete AUTO_MERGE Philippe Blain via GitGitGadget
` (2 subsequent siblings)
7 siblings, 0 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-05-22 19:29 UTC (permalink / raw)
To: git
Cc: Elijah Newren, Johannes Schindelin, Victoria Dye, Taylor Blau,
Eric Sunshine, Felipe Contreras, Philippe Blain, Chris Torek,
Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
Since 5291828df8 (merge-ort: write $GIT_DIR/AUTO_MERGE whenever we hit a
conflict, 2021-03-20), when using the 'ort' merge strategy, the special
ref AUTO_MERGE is written when a merge operation results in conflicts.
This ref points to a tree recording the conflicted state of the working
tree and is very useful during conflict resolution. However, this ref is
not documented.
Add some documentation for AUTO_MERGE in git-diff(1), git-merge(1),
gitrevisions(7) and in the user manual.
In git-diff(1), mention it at the end of the description section, when
we mention that the command also accepts trees instead of commits, and
also add an invocation to the "Various ways to check your working tree"
example.
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"
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
special refs.
In the user manual, add a paragraph describing AUTO_MERGE to the
"Getting conflict-resolution help during a merge" section, and include
an example of a 'git diff AUTO_MERGE' invocation for the example
conflict used in that section. Note that for uniformity we do not use
backticks around AUTO_MERGE here since the rest of the document does not
typeset special refs differently.
Closes: https://github.com/gitgitgadget/git/issues/1471
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
Documentation/git-diff.txt | 9 ++++++++-
Documentation/git-merge.txt | 9 +++++++--
Documentation/revisions.txt | 7 ++++++-
Documentation/user-manual.txt | 27 +++++++++++++++++++++++++++
4 files changed, 48 insertions(+), 4 deletions(-)
diff --git a/Documentation/git-diff.txt b/Documentation/git-diff.txt
index 52b679256c4..08087ffad5f 100644
--- a/Documentation/git-diff.txt
+++ b/Documentation/git-diff.txt
@@ -102,7 +102,11 @@ If --merge-base is given, use the merge base of the two commits for the
Just in case you are doing something exotic, it should be
noted that all of the <commit> in the above description, except
in the `--merge-base` case and in the last two forms that use `..`
-notations, can be any <tree>.
+notations, can be any <tree>. A tree of interest is the one pointed to
+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 textual conflicts (see the examples below).
For a more complete list of ways to spell <commit>, see
"SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
@@ -152,6 +156,7 @@ Various ways to check your working tree::
$ git diff <1>
$ git diff --cached <2>
$ git diff HEAD <3>
+$ git diff AUTO_MERGE <4>
------------
+
<1> Changes in the working tree not yet staged for the next commit.
@@ -159,6 +164,8 @@ $ 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 textual
+ conflicts so far.
Comparing with arbitrary commits::
+
diff --git a/Documentation/git-merge.txt b/Documentation/git-merge.txt
index 23aefe28851..8625c5cb0ec 100644
--- a/Documentation/git-merge.txt
+++ b/Documentation/git-merge.txt
@@ -196,7 +196,11 @@ happens:
can inspect the stages with `git ls-files -u`). The working
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 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,
i.e. matching `HEAD`.
@@ -336,7 +340,8 @@ You can work through the conflict with a number of tools:
* Look at the diffs. `git diff` will show a three-way diff,
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 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
diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt
index b34f981622b..6ea6c7cead1 100644
--- a/Documentation/revisions.txt
+++ b/Documentation/revisions.txt
@@ -33,7 +33,8 @@ 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`);
+ `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD`, `BISECT_HEAD`
+ and `AUTO_MERGE`);
. otherwise, 'refs/<refname>' if it exists;
@@ -71,6 +72,10 @@ 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
diff --git a/Documentation/user-manual.txt b/Documentation/user-manual.txt
index dc9c6a663a9..aa385137adc 100644
--- a/Documentation/user-manual.txt
+++ b/Documentation/user-manual.txt
@@ -1343,6 +1343,33 @@ $ git diff -3 file.txt # diff against stage 3
$ git diff --theirs file.txt # same as the above.
-------------------------------------------------
+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 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:
+
+-------------------------------------------------
+$ git diff AUTO_MERGE
+diff --git a/file.txt b/file.txt
+index cd10406..8bf5ae7 100644
+--- a/file.txt
++++ b/file.txt
+@@ -1,5 +1 @@
+-<<<<<<< HEAD:file.txt
+-Hello world
+-=======
+-Goodbye
+->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
++Goodbye world
+-------------------------------------------------
+
+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:
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* [PATCH v2 6/6] completion: complete AUTO_MERGE
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
` (4 preceding siblings ...)
2023-05-22 19:29 ` [PATCH v2 5/6] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
@ 2023-05-22 19:29 ` Philippe Blain via GitGitGadget
2023-06-01 6:18 ` [PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs Elijah Newren
2023-06-01 7:30 ` Junio C Hamano
7 siblings, 0 replies; 35+ messages in thread
From: Philippe Blain via GitGitGadget @ 2023-05-22 19:29 UTC (permalink / raw)
To: git
Cc: Elijah Newren, Johannes Schindelin, Victoria Dye, Taylor Blau,
Eric Sunshine, Felipe Contreras, Philippe Blain, Chris Torek,
Philippe Blain, Philippe Blain
From: Philippe Blain <levraiphilippeblain@gmail.com>
The pseudoref AUTO_MERGE is documented since the previous commit. To
make it easier to use, let __git_refs in the Bash completion code
complete it.
Signed-off-by: Philippe Blain <levraiphilippeblain@gmail.com>
---
contrib/completion/git-completion.bash | 2 +-
1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/contrib/completion/git-completion.bash b/contrib/completion/git-completion.bash
index bcda376735c..945d2543b07 100644
--- a/contrib/completion/git-completion.bash
+++ b/contrib/completion/git-completion.bash
@@ -767,7 +767,7 @@ __git_refs ()
track=""
;;
*)
- for i in HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD REBASE_HEAD CHERRY_PICK_HEAD REVERT_HEAD BISECT_HEAD; do
+ for i in HEAD FETCH_HEAD ORIG_HEAD MERGE_HEAD REBASE_HEAD CHERRY_PICK_HEAD REVERT_HEAD BISECT_HEAD AUTO_MERGE; do
case "$i" in
$match*|$umatch*)
if [ -e "$dir/$i" ]; then
--
gitgitgadget
^ permalink raw reply related [flat|nested] 35+ messages in thread
* Re: [PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
` (5 preceding siblings ...)
2023-05-22 19:29 ` [PATCH v2 6/6] completion: complete AUTO_MERGE Philippe Blain via GitGitGadget
@ 2023-06-01 6:18 ` Elijah Newren
2023-06-01 7:32 ` Junio C Hamano
2023-06-01 7:30 ` Junio C Hamano
7 siblings, 1 reply; 35+ messages in thread
From: Elijah Newren @ 2023-06-01 6:18 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Johannes Schindelin, Victoria Dye, Taylor Blau,
Eric Sunshine, Felipe Contreras, Philippe Blain, Chris Torek
On Mon, May 22, 2023 at 12:29 PM Philippe Blain via GitGitGadget
<gitgitgadget@gmail.com> wrote:
>
> 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.
I re-read the whole series. It addresses all the things I brought up
in v1 (except the bonus idea I threw out there about mentioning how
AUTO_MERGE is related to --remerge-diff), and all the things I
remember others bringing up as well.
Reviewed-by: Elijah Newren <newren@gmail.com>
Thanks for working on this!
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
` (6 preceding siblings ...)
2023-06-01 6:18 ` [PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs Elijah Newren
@ 2023-06-01 7:30 ` Junio C Hamano
7 siblings, 0 replies; 35+ messages in thread
From: Junio C Hamano @ 2023-06-01 7:30 UTC (permalink / raw)
To: Philippe Blain via GitGitGadget
Cc: git, Elijah Newren, Johannes Schindelin, Victoria Dye,
Taylor Blau, Eric Sunshine, Felipe Contreras, Philippe Blain,
Chris Torek
"Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com> writes:
> 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.
OK. Let's eject what is in 'next' then.
^ permalink raw reply [flat|nested] 35+ messages in thread
* Re: [PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs
2023-06-01 6:18 ` [PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs Elijah Newren
@ 2023-06-01 7:32 ` Junio C Hamano
0 siblings, 0 replies; 35+ messages in thread
From: Junio C Hamano @ 2023-06-01 7:32 UTC (permalink / raw)
To: Elijah Newren
Cc: Philippe Blain via GitGitGadget, git, Johannes Schindelin,
Victoria Dye, Taylor Blau, Eric Sunshine, Felipe Contreras,
Philippe Blain, Chris Torek
Elijah Newren <newren@gmail.com> writes:
> I re-read the whole series. It addresses all the things I brought up
> in v1 (except the bonus idea I threw out there about mentioning how
> AUTO_MERGE is related to --remerge-diff), and all the things I
> remember others bringing up as well.
>
> Reviewed-by: Elijah Newren <newren@gmail.com>
>
> Thanks for working on this!
Thanks.
The previous one I'd discard and replace with this one when opening
the tree for the next cycle.
^ permalink raw reply [flat|nested] 35+ messages in thread
end of thread, other threads:[~2023-06-01 7:32 UTC | newest]
Thread overview: 35+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2023-04-14 17:58 [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Philippe Blain via GitGitGadget
2023-04-14 17:58 ` [PATCH 1/5] revisions.txt: document " Philippe Blain via GitGitGadget
2023-04-14 18:49 ` Junio C Hamano
2023-04-15 5:18 ` Felipe Contreras
2023-04-14 19:49 ` Victoria Dye
2023-04-14 21:14 ` Taylor Blau
2023-04-15 5:35 ` Felipe Contreras
2023-04-14 17:58 ` [PATCH 2/5] completion: complete REVERT_HEAD and BISECT_HEAD Philippe Blain via GitGitGadget
2023-04-14 20:25 ` Junio C Hamano
2023-04-14 17:58 ` [PATCH 3/5] git-merge.txt: modernize word choice in "True merge" section Philippe Blain via GitGitGadget
2023-04-14 20:36 ` Junio C Hamano
2023-04-14 17:58 ` [PATCH 4/5] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
2023-04-14 21:41 ` Taylor Blau
2023-04-15 5:08 ` Eric Sunshine
2023-04-15 7:08 ` Elijah Newren
2023-04-15 8:55 ` Eric Sunshine
2023-04-16 3:05 ` Elijah Newren
2023-04-15 7:03 ` Elijah Newren
2023-04-15 15:36 ` Philippe Blain
2023-04-15 23:31 ` Elijah Newren
2023-04-14 17:58 ` [PATCH 5/5] completion: complete AUTO_MERGE Philippe Blain via GitGitGadget
2023-04-14 18:34 ` [PATCH 0/5] Document 'AUTO_MERGE' and more special refs Junio C Hamano
2023-04-14 19:49 ` Victoria Dye
2023-04-15 7:09 ` Elijah Newren
2023-04-16 10:26 ` Chris Torek
2023-05-22 19:28 ` [PATCH v2 0/6] " Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 1/6] revisions.txt: use description list for " Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 2/6] revisions.txt: document more " Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 3/6] completion: complete REVERT_HEAD and BISECT_HEAD Philippe Blain via GitGitGadget
2023-05-22 19:28 ` [PATCH v2 4/6] git-merge.txt: modernize word choice in "True merge" section Philippe Blain via GitGitGadget
2023-05-22 19:29 ` [PATCH v2 5/6] Documentation: document AUTO_MERGE Philippe Blain via GitGitGadget
2023-05-22 19:29 ` [PATCH v2 6/6] completion: complete AUTO_MERGE Philippe Blain via GitGitGadget
2023-06-01 6:18 ` [PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs Elijah Newren
2023-06-01 7:32 ` Junio C Hamano
2023-06-01 7:30 ` Junio C Hamano
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).