[v3,0/6] doc: update-ref: amend old material and discuss symrefs

Commit Message

Kristoffer Haugsbakk Oct. 21, 2024, 8:47 p.m. UTC

From: Kristoffer Haugsbakk <[e-mail]>

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:
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 <[e-mail]>
     
     
      ## Notes (series) ##
    +    v3:
    +    • Also add missing “that”: “after verifying *that*”
    +
    +      Link: https://lore.kernel.org/git/CAOLa=[e-mail]/
         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 <[e-mail]>
     
    +
    + ## Notes (series) ##
    +    v3:
    +    • Change commit message: ref backends
    +
    +      Link: https://lore.kernel.org/git/[e-mail]/#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

Comments

Taylor Blau Oct. 21, 2024, 8:50 p.m. UTC | #1

On Mon, Oct 21, 2024 at 10:47:23PM +0200, [e-mail] wrote:
>  Documentation/git-symbolic-ref.txt |  4 +++
>  Documentation/git-update-ref.txt   | 48 +++++++++++++-----------------
>  2 files changed, 25 insertions(+), 27 deletions(-)

Thanks, this version looks quite good to me. Are we ready to start
merging this round down?

(I saw that Karthik had suggested that 'v2' was already looking good to
them, but it would be nice to get a similar ack on this latest round).

Thanks,
Taylor

Patch

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