diff mbox series

[v3,4/6] Documentation/git-update-ref.txt: remove confusing paragraph

Message ID f6a70b3f70a8d92a40c2079961e1b060e891cf23.1729543007.git.code@khaugsbakk.name (mailing list archive)
State Accepted
Commit 793e308f1ed8197764cce8b88b4ee4e7471287df
Headers show
Series [v3,1/6] Documentation/git-update-ref.txt: drop “flag” | expand

Commit Message

Kristoffer Haugsbakk Oct. 21, 2024, 8:47 p.m. UTC 
From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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
confuse the reader about what argument can be a symbolic ref since it
just says “it” and not which of the parameters; in turn the reader can
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):
    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 | 4 ----
 1 file changed, 4 deletions(-)
diff mbox series

Patch

diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt
index 6aaa7339d71..61647ee8413 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.txt
@@ -25,10 +25,6 @@  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
 not exist.
 
-It also allows a "ref" file to be a symbolic pointer to another
-ref file by starting with the four-byte header sequence of
-"ref:".
-
 If --no-deref is given, <ref> itself is overwritten, rather than
 the result of following the symbolic pointers.