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

[kristofferhaugsbakk@fastmail.com]

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