| Message ID | 0cdd4ab3d739e07357ea9efef2cdece633db6ebb.1681495119.git.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| State | Accepted |
| Commit | 55aadccf1491dd01131213f6aa35b807567b65b5 |
| Headers | show |
| Series | Document 'AUTO_MERGE' and more special refs | expand |
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
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"?
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 >
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.
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.
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...
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`).
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.
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: