From: "Philippe Blain via GitGitGadget" <gitgitgadget@gmail.com>
To: git@vger.kernel.org
Cc: Elijah Newren <newren@gmail.com>,
Johannes Schindelin <Johannes.Schindelin@gmx.de>,
Philippe Blain <levraiphilippeblain@gmail.com>,
Philippe Blain <levraiphilippeblain@gmail.com>
Subject: [PATCH 4/5] Documentation: document AUTO_MERGE
Date: Fri, 14 Apr 2023 17:58:37 +0000 [thread overview]
Message-ID: <0cdd4ab3d739e07357ea9efef2cdece633db6ebb.1681495119.git.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1515.git.1681495119.gitgitgadget@gmail.com>
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
next prev parent reply other threads:[~2023-04-14 17:59 UTC|newest]
Thread overview: 35+ messages / expand[flat|nested] mbox.gz Atom feed top
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 ` Philippe Blain via GitGitGadget [this message]
2023-04-14 21:41 ` [PATCH 4/5] Documentation: document AUTO_MERGE 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
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=0cdd4ab3d739e07357ea9efef2cdece633db6ebb.1681495119.git.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=Johannes.Schindelin@gmx.de \
--cc=git@vger.kernel.org \
--cc=levraiphilippeblain@gmail.com \
--cc=newren@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
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).