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

From: kristofferhaugsbakk@fastmail.com <kristofferhaugsbakk@fastmail.com>
Date: Oct 19, 2024, 19:59 UTC
Message-ID: <cover.1729367469.git.code@khaugsbakk.name>
In-Reply-To: <cover.1729017728.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 v2

See notes on the patches for all changes. Some of the minor ones are omitted here.

• Diff changes (see interdiff):
  • Fix “the the”
• All: Taylor suggested changing the “area” prefix
  • (but I kept it on the series for consistency)
  • Link: https://lore.kernel.org/git/ZxAoFUDmdfZ8rlLs@nand.local/
• Patch “drop “flag” ”:
  • Not done: Wrap paragraph
• Patch “remove confusing paragraph”
  • (Commit) Message tweak
  • Mention that what a symref is (concretely) is documented elsewhere
• Patch “discuss symbolic refs”:
  • change subject from “symbolic links”
  • Credit Bence

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 v1:

diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt
index fada3f670eb..c64d80f5a2d 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.txt
@@ -28,8 +28,8 @@ not exist.
 The final arguments are object names; this command without any options
 does not support updating a symbolic ref to point to another ref (see
 linkgit:git-symbolic-ref[1]).  But `git update-ref --stdin` does have
-the the `symref-*` commands so that regular refs and symbolic refs can
-be committed in the same transaction.
+the `symref-*` commands so that regular refs and symbolic refs can be
+committed in the same transaction.
 
 If --no-deref is given, <ref> itself is overwritten, rather than
 the result of following the symbolic pointers.
Range-diff against v1:
1:  ad9ee00a2a9 ! 1:  91c1cae3209 doc: update-ref: drop “flag”
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: update-ref: drop “flag”
    +    Documentation/git-update-ref.txt: drop “flag”
     
    -    The other paragraphs on options say `With <option>,`.  Let’s be uniform.
    +    The other paragraphs on options say “With <option>,”.  Let’s be uniform.
     
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +    • Message: tweak
    +    • Not done: paragraph wrapping.  I found something else in this
    +      paragraph: missing “that”: “after verifying *that*”.  I will fix that
    +      in an upcoming series since there were four other missing instances of
    +      this word and I did not want to add another patch to this series.
    +
      ## Documentation/git-update-ref.txt ##
     @@ Documentation/git-update-ref.txt: for reading but not for writing (so we'll never write through a
      ref symlink to some other tree, if you have copied a whole
2:  c4bc0553a30 ! 2:  71d1e6364a2 doc: update-ref: remove safety paragraphs
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: update-ref: remove safety paragraphs
    +    Documentation/git-update-ref.txt: remove safety paragraphs
     
         Remove paragraphs which explain that using this command is safer than
         echoing the branch name into `HEAD`.
3:  3f43ddfed24 ! 3:  ca786bff978 doc: update-ref: demote symlink to last section
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: update-ref: demote symlink to last section
    +    Documentation/git-update-ref.txt: demote symlink to last section
     
         Move the discussion of file system symbolic links to a new “Notes”
         section (inspired by the one in git-symbolic-ref(1)) since this is
4:  dec48e2d37c ! 4:  769fd20945d doc: update-ref: remove confusing paragraph
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: update-ref: remove confusing paragraph
    +    Documentation/git-update-ref.txt: remove confusing paragraph
     
    -    This paragraph interrupts the flow of this section by going into detail
    +    This paragraph interrupts the flow of the section by going into detail
         about what a symbolic ref file is and how it is implemented.  It is not
         clear what the purpose is since symbolic refs were already mentioned
         prior (“possibly dereferencing the symbolic refs”).  Worse, it can
    @@ Commit message
         be lead to try `<new-oid>` and then get a confusing error since
         update-ref will just say that it is not a valid SHA1.
     
    +    gitglossary(7) already documents what a symref is, concretely, and quite
    +    well at that.
    +
         Reported-by: Bence Ferdinandy <bence@ferdinandy.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
     
      ## Notes (series) ##
    -    This paragraph is also from the initial documentation: 129056370ab (Add
    -    missing documentation., 2005-10-04).
    +    v2:
    +    • Message: replace “this” with “the”, which avoids two “this” close to
    +      each other
    +    • Message: Mention that what a symref is (concretely) is covered
    +      by gitglossary(7)
     
      ## Documentation/git-update-ref.txt ##
     @@ Documentation/git-update-ref.txt: value is <old-oid>.  You can specify 40 "0" or an empty string
5:  3575fb48c93 ! 5:  ca5ece5336c doc: update-ref: discuss symbolic links
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: update-ref: discuss symbolic links
    +    Documentation/git-update-ref.txt: discuss symbolic refs
     
         Add a paragraph which just emphasizes that the command without any
    -    options does not support refs in the final arguments.  This is
    -    clear already from the names `<new-oid>` and `<old-oid>` but the right
    -    balance of redundancy makes documentation robust to stray
    -    interpretation.
    +    options does not support refs in the final arguments.  This is clear
    +    already from the names `<new-oid>` and `<old-oid>` but the right balance
    +    of redundancy makes documentation robust against stray interpretation.
     
         This is also a good place to mention why `--stdin` has those `symref-*`
         commands.
     
    +    Suggested-by: Bence Ferdinandy <bence@ferdinandy.com>
         Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
    +
    + ## Notes (series) ##
    +    v2:
    +    • Message: grammar: “robust against”
    +    • Message: Apparently the first paragraph wasn’t wrapped properly
    +    • Fix “the the”
    +    • Credit Bence for this suggestion which I forgot to do in v1
    +
    +      Link: https://lore.kernel.org/git/D4U30MD29CJT.3US5SBR598DVY@ferdinandy.com/
    +    • Message: “symbolic refs”, not links
    +
      ## Documentation/git-update-ref.txt ##
     @@ Documentation/git-update-ref.txt: value is <old-oid>.  You can specify 40 "0" or an empty string
      as <old-oid> to make sure that the ref you are creating does
    @@ Documentation/git-update-ref.txt: value is <old-oid>.  You can specify 40 "0" or
     +The final arguments are object names; this command without any options
     +does not support updating a symbolic ref to point to another ref (see
     +linkgit:git-symbolic-ref[1]).  But `git update-ref --stdin` does have
    -+the the `symref-*` commands so that regular refs and symbolic refs can
    -+be committed in the same transaction.
    ++the `symref-*` commands so that regular refs and symbolic refs can be
    ++committed in the same transaction.
     +
      If --no-deref is given, <ref> itself is overwritten, rather than
      the result of following the symbolic pointers.
6:  9e775a65eb3 ! 6:  fd3c7585a0f doc: mutually link update-ref and symbolic-ref
    @@ Metadata
     Author: Kristoffer Haugsbakk <code@khaugsbakk.name>
     
      ## Commit message ##
    -    doc: mutually link update-ref and symbolic-ref
    +    Documentation: mutually link update-ref and symbolic-ref
     
         These two commands are similar enough to acknowledge each other on their
         documentation pages.

base-commit: ef8ce8f3d4344fd3af049c17eeba5cd20d98b69f

-- 
2.46.1.641.g54e7913fcb6