From: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx>
This series removes or moves some old material in the update-ref doc and
improves the discussion of symrefs, opting for a high-level description
with some redundancy (see patch 5/6) in order to avoid a reported
mistake/confusion.
The end goal (after all patches are applied):
• First paragraph (in Description) describes the first form
• Second paragraph the second form
• Third paragraph mentions symrefs and explains why `--stdin` supports
them
• A new section whither the symlink (FS) vs. symrefs discussion is moved
• Link update-ref to symbolic-ref and vice versa
§ Changes in v3
• Diff changes (see interdiff):
• Add missing word “that”
• Patch “remove confusing paragraph”
• Rewrite message to emphasize ref backends
• Patch “drop “flag” ”:
• Add missing word “that”
Kristoffer Haugsbakk (6):
Documentation/git-update-ref.txt: drop “flag”
Documentation/git-update-ref.txt: remove safety paragraphs
Documentation/git-update-ref.txt: demote symlink to last section
Documentation/git-update-ref.txt: remove confusing paragraph
Documentation/git-update-ref.txt: discuss symbolic refs
Documentation: mutually link update-ref and symbolic-ref
Documentation/git-symbolic-ref.txt | 4 +++
Documentation/git-update-ref.txt | 48 +++++++++++++-----------------
2 files changed, 25 insertions(+), 27 deletions(-)
Interdiff against v2:
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt
index c64d80f5a2d..8a4281cde9f 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.txt
@@ -34,7 +34,7 @@ committed in the same transaction.
If --no-deref is given, <ref> itself is overwritten, rather than
the result of following the symbolic pointers.
-With `-d`, it deletes the named <ref> after verifying it
+With `-d`, it deletes the named <ref> after verifying that it
still contains <old-oid>.
With `--stdin`, update-ref reads instructions from standard input and
Range-diff against v2:
1: 91c1cae3209 ! 1: 9c40351950f Documentation/git-update-ref.txt: drop “flag”
@@ Commit message
The other paragraphs on options say “With <option>,”. Let’s be uniform.
+ Also add missing word “that”.
+
Signed-off-by: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx>
## Notes (series) ##
+ v3:
+ • Also add missing “that”: “after verifying *that*”
+
+ Link: https://lore.kernel.org/git/CAOLa=ZTJqcEOQm8Ns58t6DxEXYn2ws__HDRRAaAhsBkJJFLXmg@xxxxxxxxxxxxxx/
v2:
• Message: tweak
• Not done: paragraph wrapping. I found something else in this
@@ Documentation/git-update-ref.txt: for reading but not for writing (so we'll neve
archive by creating a symlink tree).
-With `-d` flag, it deletes the named <ref> after verifying it
-+With `-d`, it deletes the named <ref> after verifying it
++With `-d`, it deletes the named <ref> after verifying that it
still contains <old-oid>.
With `--stdin`, update-ref reads instructions from standard input and
2: 71d1e6364a2 ! 2: bb14c427f81 Documentation/git-update-ref.txt: remove safety paragraphs
@@ Commit message
Remove paragraphs which explain that using this command is safer than
echoing the branch name into `HEAD`.
- These paragraphs have been part of the documentation since the
- documentation was created in 129056370ab (Add missing documentation.,
- 2005-10-04), back when the command synopsis was a lot simpler:
+ Evoking the echo strategy is wrong now under the reftable backend since
+ this file does not exist. And the ref file backend majority user base
+ use porcelain commands to manage `HEAD` unless they are intentionally
+ poking at the implementation.
- `git-update-ref` <ref> <newvalue> [<oldvalue>]
+ Maybe this warning was relevant for the usage patterns when it was
+ added[1] but now it just takes up space.
- These paragraphs don’t interrupt the flow of the document on that
- revision since it is at the end. Now though it is placed after the
- description of `--no-deref` and before `-d` and `--stdin`. Covering all
- the options is more generally interesting than a safety note about a
- naïve `HEAD` management.
-
- Such a safety warning is also much less relevant now, considering that
- everyone who isn’t intentionally poking at the internal implementation
- is using porcelain commands to manage `HEAD`.
+ † 1: 129056370ab (Add missing documentation., 2005-10-04)
Signed-off-by: Kristoffer Haugsbakk <code@xxxxxxxxxxxxxxx>
+
+ ## Notes (series) ##
+ v3:
+ • Change commit message: ref backends
+
+ Link: https://lore.kernel.org/git/bcb0e2d8-ebee-4835-aa43-05107199ee62@xxxxxxxxxxxxxxxx/#t
+
## Documentation/git-update-ref.txt ##
@@ Documentation/git-update-ref.txt: somewhere else with a regular filename).
If --no-deref is given, <ref> itself is overwritten, rather than
@@ Documentation/git-update-ref.txt: somewhere else with a regular filename).
-ref symlink to some other tree, if you have copied a whole
-archive by creating a symlink tree).
-
- With `-d`, it deletes the named <ref> after verifying it
+ With `-d`, it deletes the named <ref> after verifying that it
still contains <old-oid>.
3: ca786bff978 = 3: 6c8ff72c230 Documentation/git-update-ref.txt: demote symlink to last section
4: 769fd20945d = 4: f6a70b3f70a Documentation/git-update-ref.txt: remove confusing paragraph
5: ca5ece5336c = 5: 5033ec82586 Documentation/git-update-ref.txt: discuss symbolic refs
6: fd3c7585a0f = 6: aa1ee4a8ee0 Documentation: mutually link update-ref and symbolic-ref
base-commit: ef8ce8f3d4344fd3af049c17eeba5cd20d98b69f
--
2.46.1.641.g54e7913fcb6
