diff mbox series

[2/6] doc: update-ref: remove safety paragraphs

Message ID c4bc0553a30ac16bd242edf387280eea37aa3a07.1729017728.git.code@khaugsbakk.name (mailing list archive)
State New
Headers show
Series doc: update-ref: amend old material and discuss symrefs | expand

Commit Message

Kristoffer Haugsbakk Oct. 15, 2024, 7:03 p.m. UTC 
From: Kristoffer Haugsbakk <code@khaugsbakk.name>

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:

    `git-update-ref` <ref> <newvalue> [<oldvalue>]

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`.

Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name>
---
 Documentation/git-update-ref.txt | 15 ---------------
 1 file changed, 15 deletions(-)

Comments

Taylor Blau Oct. 16, 2024, 8:47 p.m. UTC | #1 
On Tue, Oct 15, 2024 at 09:03:11PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> 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`.

Makes sense. Thanks for carefully explaining your reasoning here.

Thanks,
Taylor
diff mbox series

Patch

diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt
index fe5967234e9..ec268b1426d 100644
--- a/Documentation/git-update-ref.txt
+++ b/Documentation/git-update-ref.txt
@@ -40,21 +40,6 @@  somewhere else with a regular filename).
 If --no-deref is given, <ref> itself is overwritten, rather than
 the result of following the symbolic pointers.
 
-In general, using
-
-	git update-ref HEAD "$head"
-
-should be a _lot_ safer than doing
-
-	echo "$head" > "$GIT_DIR/HEAD"
-
-both from a symlink following standpoint *and* an error checking
-standpoint.  The "refs/" rule for symlinks means that symlinks
-that point to "outside" the tree are safe: they'll be followed
-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
-archive by creating a symlink tree).
-
 With `-d`, it deletes the named <ref> after verifying it
 still contains <old-oid>.