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>,
Victoria Dye <vdye@github.com>, Taylor Blau <me@ttaylorr.com>,
Eric Sunshine <sunshine@sunshineco.com>,
Felipe Contreras <felipe.contreras@gmail.com>,
Philippe Blain <levraiphilippeblain@gmail.com>,
Chris Torek <chris.torek@gmail.com>,
Philippe Blain <levraiphilippeblain@gmail.com>
Subject: [PATCH v2 0/6] Document 'AUTO_MERGE' and more special refs
Date: Mon, 22 May 2023 19:28:55 +0000 [thread overview]
Message-ID: <pull.1515.v2.git.1684783741.gitgitgadget@gmail.com> (raw)
In-Reply-To: <pull.1515.git.1681495119.gitgitgadget@gmail.com>
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
next prev parent reply other threads:[~2023-05-22 19:29 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 ` [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 ` Philippe Blain via GitGitGadget [this message]
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=pull.1515.v2.git.1684783741.gitgitgadget@gmail.com \
--to=gitgitgadget@gmail.com \
--cc=Johannes.Schindelin@gmx.de \
--cc=chris.torek@gmail.com \
--cc=felipe.contreras@gmail.com \
--cc=git@vger.kernel.org \
--cc=levraiphilippeblain@gmail.com \
--cc=me@ttaylorr.com \
--cc=newren@gmail.com \
--cc=sunshine@sunshineco.com \
--cc=vdye@github.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).