| Message ID | 71d1e6364a21767a8d80c96a30282e6557fec426.1729367469.git.code@khaugsbakk.name (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v2,1/6] Documentation/git-update-ref.txt: drop “flag” | expand |
kristofferhaugsbakk@fastmail.com writes: > 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(-) > > 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). > - In the new reftable backend, HEAD would simply exist as a placeholder. So either we do as you did and remove this entirely or double down to say that writing to HEAD directly is not supported. I don't have a preference here, so this looks good!
On Sun, Oct 20, 2024, at 13:13, karthik nayak wrote: >> […] >> 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`. >> […] > > In the new reftable backend, HEAD would simply exist as a placeholder. > So either we do as you did and remove this entirely or double down to > say that writing to HEAD directly is not supported. I don't have a > preference here, so this looks good! Great, thanks. :) Here’s an attempted rewrite of the final paragraph for the possible next round: “ [Besides,] Writing to `HEAD` with `echo` is not allowed under the reftable implementation, so this part has become misleading. But now it doesn’t make sense to write multiple paragraphs and then end with the most important part. Maybe “ Remove paragraphs which explain that using this command is safer than echoing the branch name into `HEAD`. Evoking the echo strategy is wrong now under the reftable backend since such a file does not exist. And these days people use porcelain commands to manage `HEAD` unless they are intentionally poking at what the ref files backend looks like. Maybe this warning was relevant for the usage patterns when it was added[1] but now it just takes up space. † 1: 129056370ab (Add missing documentation., 2005-10-04)
On Sun, Oct 20, 2024, at 13:13, karthik nayak wrote: > kristofferhaugsbakk@fastmail.com writes: >> […] >> 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`. >> >> […] > > In the new reftable backend, HEAD would simply exist as a placeholder. > So either we do as you did and remove this entirely or double down to > say that writing to HEAD directly is not supported. I don't have a > preference here, so this looks good! I see now that I misread you. I thought you were talking about the commit message. But you’re talking about the doc text. I don’t think that this text needs to say that writing to `HEAD` is not supported. Now the doc has implied that writing to `HEAD` is an option since 2005. But I think that implication has been irrelevant for a long time. We’re far away from the time when people had to update `HEAD` manually.
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>.