[PATCH v3 0/6] doc: update-ref: amend old material and discuss symrefs
- From
- kristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
- Date
- Oct 21, 2024, 20:47 UTC
- Message-ID
- <cover.1729543007.git.code@khaugsbakk.name>
- In-Reply-To
- <cover.1729367469.git.code@khaugsbakk.name>
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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@khaugsbakk.name> ## Notes (series) ## + v3: + • Also add missing “that”: “after verifying *that*” + + Link: https://lore.kernel.org/git/CAOLa=ZTJqcEOQm8Ns58t6DxEXYn2ws__HDRRAaAhsBkJJFLXmg@mail.gmail.com/ 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@khaugsbakk.name> + + ## Notes (series) ## + v3: + • Change commit message: ref backends + + Link: https://lore.kernel.org/git/bcb0e2d8-ebee-4835-aa43-05107199ee62@app.fastmail.com/#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