| Message ID | pull.1515.v2.git.1684783741.gitgitgadget@gmail.com (mailing list archive) |
|---|---|
| Headers | show |
| Series | Document 'AUTO_MERGE' and more special refs | expand |
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!
"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.
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.
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