@matheusbsbs / matheus-bagliano / commits / 4fa1edb988

Documentation: document AUTO_MERGE

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> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Philippe Blain committed May 22, 2023 at 19:29 UTC 4fa1edb98820ec6ddf52b004f9d616c34a8ddfd2
4 files changed +48 -4
Documentation/git-diff.txt
+8 -1
@@ -102,7 +102,11 @@ If --merge-base is given, use the merge base of the two commits for the
102 Just in case you are doing something exotic, it should be
103 noted that all of the <commit> in the above description, except
104 in the `--merge-base` case and in the last two forms that use `..`
105 -notations, can be any <tree>.
105 +notations, can be any <tree>. A tree of interest is the one pointed to
106 +by the special ref `AUTO_MERGE`, which is written by the 'ort' merge
107 +strategy upon hitting merge conflicts (see linkgit:git-merge[1]).
108 +Comparing the working tree with `AUTO_MERGE` shows changes you've made
109 +so far to resolve textual conflicts (see the examples below).
110
111 For a more complete list of ways to spell <commit>, see
112 "SPECIFYING REVISIONS" section in linkgit:gitrevisions[7].
@@ -152,6 +156,7 @@ Various ways to check your working tree::
156 $ git diff <1>
157 $ git diff --cached <2>
158 $ git diff HEAD <3>
159 +$ git diff AUTO_MERGE <4>
160 ------------
161 +
162 <1> Changes in the working tree not yet staged for the next commit.
@@ -159,6 +164,8 @@ $ git diff HEAD <3>
164 would be committing if you run `git commit` without `-a` option.
165 <3> Changes in the working tree since your last commit; what you
166 would be committing if you run `git commit -a`
167 +<4> Changes in the working tree you've made to resolve textual
168 + conflicts so far.
169
170 Comparing with arbitrary commits::
171 +
Documentation/git-merge.txt
+7 -2
@@ -196,7 +196,11 @@ happens:
196 can inspect the stages with `git ls-files -u`). The working
197 tree files contain the result of the merge operation; i.e. 3-way
198 merge results with familiar conflict markers `<<<` `===` `>>>`.
199 -5. No other changes are made. In particular, the local
199 +5. A special ref `AUTO_MERGE` is written, pointing to a tree
200 + corresponding to the current content of the working tree (including
201 + conflict markers for textual conflicts). Note that this ref is only
202 + written when the 'ort' merge strategy is used (the default).
203 +6. No other changes are made. In particular, the local
204 modifications you had before you started merge will stay the
205 same and the index entries for them stay as they were,
206 i.e. matching `HEAD`.
@@ -336,7 +340,8 @@ You can work through the conflict with a number of tools:
340
341 * Look at the diffs. `git diff` will show a three-way diff,
342 highlighting changes from both the `HEAD` and `MERGE_HEAD`
339 - versions.
343 + versions. `git diff AUTO_MERGE` will show what changes you've
344 + made so far to resolve textual conflicts.
345
346 * Look at the diffs from each branch. `git log --merge -p <path>`
347 will show diffs first for the `HEAD` version and then the
Documentation/revisions.txt
+6 -1
@@ -33,7 +33,8 @@ characters and to avoid word splitting.
33 +
34 . If '$GIT_DIR/<refname>' exists, that is what you mean (this is usually
35 useful only for `HEAD`, `FETCH_HEAD`, `ORIG_HEAD`, `MERGE_HEAD`,
36 - `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD` and `BISECT_HEAD`);
36 + `REBASE_HEAD`, `REVERT_HEAD`, `CHERRY_PICK_HEAD`, `BISECT_HEAD`
37 + and `AUTO_MERGE`);
38
39 . otherwise, 'refs/<refname>' if it exists;
40
@@ -71,6 +72,10 @@ characters and to avoid word splitting.
72 `BISECT_HEAD`:::
73 records the current commit to be tested when you run `git bisect
74 --no-checkout`.
75 + `AUTO_MERGE`:::
76 + records a tree object corresponding to the state the
77 + 'ort' merge strategy wrote to the working tree when a merge operation
78 + resulted in conflicts.
79
80 +
81 Note that any of the 'refs/*' cases above may come either from
Documentation/user-manual.txt
+27
@@ -1343,6 +1343,33 @@ $ git diff -3 file.txt # diff against stage 3
1343 $ git diff --theirs file.txt # same as the above.
1344 -------------------------------------------------
1345
1346 +When using the 'ort' merge strategy (the default), before updating the working
1347 +tree with the result of the merge, Git writes a special ref named AUTO_MERGE
1348 +reflecting the state of the tree it is about to write. Conflicted paths with
1349 +textual conflicts that could not be automatically merged are written to this
1350 +tree with conflict markers, just as in the working tree. AUTO_MERGE can thus be
1351 +used with linkgit:git-diff[1] to show the changes you've made so far to resolve
1352 +conflicts. Using the same example as above, after resolving the conflict we
1353 +get:
1354 +
1355 +-------------------------------------------------
1356 +$ git diff AUTO_MERGE
1357 +diff --git a/file.txt b/file.txt
1358 +index cd10406..8bf5ae7 100644
1359 +--- a/file.txt
1360 ++++ b/file.txt
1361 +@@ -1,5 +1 @@
1362 +-<<<<<<< HEAD:file.txt
1363 +-Hello world
1364 +-=======
1365 +-Goodbye
1366 +->>>>>>> 77976da35a11db4580b80ae27e8d65caf5208086:file.txt
1367 ++Goodbye world
1368 +-------------------------------------------------
1369 +
1370 +Notice that the diff shows we deleted the conflict markers and both versions of
1371 +the content line, and wrote "Goodbye world" instead.
1372 +
1373 The linkgit:git-log[1] and linkgit:gitk[1] commands also provide special help
1374 for merges:
1375