Bence FerdinandyHi,
the documentation for `git update-ref` has this sentence:
> 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:".
After fumbling around a bit and getting errors like
fatal: ref:refs/remotes/origin/test: not a valid SHA1
I looked in builtin/update-ref.c and I do not see a call to refs_update_symref nor any checks for "ref:". Am I missing something here?
Thanks, Bence
-- bence.ferdinandy.com
Re: with git update-ref?
On Fri, Oct 11, 2024, at 22:51, Bence Ferdinandy wrote:
> Hi, > > the documentation for `git update-ref` has this sentence: > >> 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:". > > After fumbling around a bit and getting errors like > > fatal: ref:refs/remotes/origin/test: not a valid SHA1
`ref: refs/remotes/origin/test`? (space after colon)
Bence FerdinandyRe: with git update-ref?
On Fri Oct 11, 2024 at 22:56, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> wrote:
> `ref: refs/remotes/origin/test`? (space after colon)
I tried a couple of variations and no:
❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test' fatal: ref: refs/remotes/origin/test: not a valid SHA1 ❯ git update-ref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test' fatal: ref: refs/remotes/origin/test: not a valid SHA1 ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test' fatal: ref:refs/remotes/origin/test: not a valid SHA1 ❯ git update-ref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test' fatal: ref:refs/remotes/origin/test: not a valid SHA1
I guess the intended way of doing this is via git symbolic-ref anyway, but I'm curious if this should work somehow or I'm misinterpreting the meaning of that sentence.
-- bence.ferdinandy.com
Junio C HamanoRe: with git update-ref?
"Bence Ferdinandy" <bence@ferdinandy.com> writes:
> On Fri Oct 11, 2024 at 22:56, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> wrote: >> `ref: refs/remotes/origin/test`? (space after colon) > > I tried a couple of variations and no: > > ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test' > fatal: ref: refs/remotes/origin/test: not a valid SHA1 > ❯ git update-ref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test' > fatal: ref: refs/remotes/origin/test: not a valid SHA1 > ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test' > fatal: ref:refs/remotes/origin/test: not a valid SHA1 > ❯ git update-ref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test' > fatal: ref:refs/remotes/origin/test: not a valid SHA1 > > I guess the intended way of doing this is via git symbolic-ref anyway, but I'm > curious if this should work somehow or I'm misinterpreting the meaning of that > sentence.
I do not think update-ref is a tool to modify a symbolic-ref. Moreover, the mention of "ref:" is meant to be for those who are overly curious for their own good and go peek into their .git/ directory; script writers should not have to know such an implementation detail.
: ask what the current state is. $ git symbolic-ref refs/remotes/origin/HEAD fatal: ref refs/remotes/origin/HEAD is not a symbolic ref
: set it $ git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main
: inspect the result $ git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/master
Thanks.
Bence FerdinandyRe: with git update-ref?
On Fri Oct 11, 2024 at 23:28, Junio C Hamano <gitster@pobox.com> wrote:
> "Bence Ferdinandy" <bence@ferdinandy.com> writes: > >> On Fri Oct 11, 2024 at 22:56, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> wrote: >>> `ref: refs/remotes/origin/test`? (space after colon) >> >> I tried a couple of variations and no: >> >> ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test' >> fatal: ref: refs/remotes/origin/test: not a valid SHA1 >> ❯ git update-ref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test' >> fatal: ref: refs/remotes/origin/test: not a valid SHA1 >> ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test' >> fatal: ref:refs/remotes/origin/test: not a valid SHA1 >> ❯ git update-ref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test' >> fatal: ref:refs/remotes/origin/test: not a valid SHA1 >> >> I guess the intended way of doing this is via git symbolic-ref anyway, but I'm >> curious if this should work somehow or I'm misinterpreting the meaning of that >> sentence. > > I do not think update-ref is a tool to modify a symbolic-ref. > Moreover, the mention of "ref:" is meant to be for those who are > overly curious for their own good and go peek into their .git/ > directory; script writers should not have to know such an > implementation detail.
Yes, that was my impression as well, but I think it is pretty misleadning because "It also" is preceded by an entire paragraph about what you can specify with oids so it's easy to read as if you could specify a symbolic ref here. Because of the --no-deref argument it makes sense to talk about symrefs, but I'd propose to rewrite this part a bit to make it more clear. Something along the lines of referencing gitglossary(1) (thanks Andreas) for what symrefs are instead of explaining here and explicitly mentioning that it's git symbolic-ref that is for manipulating symrefs.
Best, Bence
-- bence.ferdinandy.com
Re: with git update-ref?
On 11/10/2024 22:28, Junio C Hamano wrote:
> "Bence Ferdinandy" <bence@ferdinandy.com> writes: > >> On Fri Oct 11, 2024 at 22:56, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> wrote: >>> `ref: refs/remotes/origin/test`? (space after colon) >> >> I tried a couple of variations and no: >> >> ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test' >> fatal: ref: refs/remotes/origin/test: not a valid SHA1 >> ❯ git update-ref refs/remotes/origin/HEAD 'ref: refs/remotes/origin/test' >> fatal: ref: refs/remotes/origin/test: not a valid SHA1 >> ❯ git update-ref --no-deref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test' >> fatal: ref:refs/remotes/origin/test: not a valid SHA1 >> ❯ git update-ref refs/remotes/origin/HEAD 'ref:refs/remotes/origin/test' >> fatal: ref:refs/remotes/origin/test: not a valid SHA1 >> >> I guess the intended way of doing this is via git symbolic-ref anyway, but I'm >> curious if this should work somehow or I'm misinterpreting the meaning of that >> sentence. > > I do not think update-ref is a tool to modify a symbolic-ref.
Didn't we add support for symbolic-refs to update-ref with 'kn/update-ref-symref'? Maybe it only works with --stdin? I've Cc'd Karthik for clarification on how it is supposed to work.
Best Wishes
Phillip
> Moreover, the mention of "ref:" is meant to be for those who are > overly curious for their own good and go peek into their .git/ > directory; script writers should not have to know such an > implementation detail. > > : ask what the current state is. > $ git symbolic-ref refs/remotes/origin/HEAD > fatal: ref refs/remotes/origin/HEAD is not a symbolic ref > > : set it > $ git symbolic-ref refs/remotes/origin/HEAD refs/remotes/origin/main > > : inspect the result > $ git symbolic-ref refs/remotes/origin/HEAD > refs/remotes/origin/master > > Thanks. >
Re: with git update-ref?
On Sun, Oct 13, 2024, at 11:34, Phillip Wood wrote:
>> I do not think update-ref is a tool to modify a symbolic-ref. > > Didn't we add support for symbolic-refs to update-ref with > 'kn/update-ref-symref'? Maybe it only works with --stdin? I've Cc'd > Karthik for clarification on how it is supposed to work.
Yes. The man page says that you can use the `symref-update` command with `--stdin`.
So the issue or confusion here seems to be that you have to use specific commands for symrefs. git-update-ref(1) won’t try to figure it out.
That seems in line with a plumbing command.
-- Kristoffer Haugsbakk
karthik nayakRe: with git update-ref?
"Kristoffer Haugsbakk" <kristofferhaugsbakk@fastmail.com> writes:
> On Sun, Oct 13, 2024, at 11:34, Phillip Wood wrote: >>> I do not think update-ref is a tool to modify a symbolic-ref. >> >> Didn't we add support for symbolic-refs to update-ref with >> 'kn/update-ref-symref'? Maybe it only works with --stdin? I've Cc'd >> Karthik for clarification on how it is supposed to work. > > Yes. The man page says that you can use the `symref-update` command > with `--stdin`. >
That's correct, we did indeed add support for symref in the --stdin part of `git update-ref`. To give some context, this is because we sometimes want to update regular refs and symrefs in the same transaction. While the underlying code exists, we didn't add support for symrefs without --stdin, mostly because `git symbolic-ref` already exists.
> So the issue or confusion here seems to be that you have to use specific > commands for symrefs. git-update-ref(1) won’t try to figure it out. >
I agree, the documentation here could use some cleanup. The confusion here lies around
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:".This is added to talk about how the command de-references symbolic refs, but it can be misinterpreted to mean that it does support symbolic refs on the top level.
Do either of you want to take a stab at updating the documentation here?
> That seems in line with a plumbing command. > > -- > Kristoffer Haugsbakk
Re: with git update-ref?
On Sun, Oct 13, 2024, at 14:09, karthik nayak wrote:
> > I agree, the documentation here could use some cleanup. The confusion > here lies around > > 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:". > > This is added to talk about how the command de-references symbolic refs, > but it can be misinterpreted to mean that it does support symbolic refs > on the top level. > > Do either of you want to take a stab at updating the documentation here? > >> That seems in line with a plumbing command. >> >> -- >> Kristoffer Haugsbakk > > Attachments: > * signature.asc
I wonder if the third (It also) and the fourth (about FS symlinks) could be removed. The third is confusing like Bernard said and the fourth doesn't seem relevant enough any more. Not relevant enough to be part of Description.
And the "safety" paragraphs could be moved to its own section. Because it looks like it's meant as an advice to unlearn the habits of a Git user from, I don't know, 2005 maybe.
Bence FerdinandyRe: with git update-ref?
On Sun Oct 13, 2024 at 17:39, Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> wrote:
> > On Sun, Oct 13, 2024, at 14:09, karthik nayak wrote: >> >> I agree, the documentation here could use some cleanup. The confusion >> here lies around >> >> 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:". >> >> This is added to talk about how the command de-references symbolic refs, >> but it can be misinterpreted to mean that it does support symbolic refs >> on the top level. >> >> Do either of you want to take a stab at updating the documentation here? >> >>> That seems in line with a plumbing command. >>> >>> -- >>> Kristoffer Haugsbakk >> >> Attachments: >> * signature.asc > > I wonder if the third (It also) and the fourth > (about FS symlinks) could be removed. The > third is confusing like Bernard said and the > fourth doesn't seem relevant enough any more. Not relevant enough to be part of Description. > > And the "safety" paragraphs could be moved > to its own section. Because it looks like it's meant as an advice to unlearn the habits of a Git user from, I don't know, 2005 maybe.
According to git blame on the manpage, 2005 is spot on :)
-- bence.ferdinandy.com
Re: with git update-ref?
On Sun, Oct 13, 2024, at 14:09, karthik nayak wrote:
> 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:". > > This is added to talk about how the command de-references symbolic refs, > but it can be misinterpreted to mean that it does support symbolic refs > on the top level. > > Do either of you want to take a stab at updating the documentation here?
I have some ideas. I think I should have something ready later this evening.
-- Kristoffer Haugsbakk
[PATCH 0/6] doc: update-ref: amend old material and discuss symrefs
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
(See the previous email for the context)
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 (`ref: ` files… or strings nowadays with the different formats that refs can have?) discussion is moved • Link update-ref to symbolic-ref and vice versa
Kristoffer Haugsbakk (6): doc: update-ref: drop “flag” doc: update-ref: remove safety paragraphs doc: update-ref: demote symlink to last section doc: update-ref: remove confusing paragraph doc: update-ref: discuss symbolic links doc: 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(-)
base-commit: ef8ce8f3d4344fd3af049c17eeba5cd20d98b69f
-- 2.46.1.641.g54e7913fcb6
[PATCH 1/6] doc: update-ref: drop “flag”
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
The other paragraphs on options say `With <option>,`. Let’s be uniform.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> --- Documentation/git-update-ref.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index afcf33cf608..fe5967234e9 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -55,7 +55,7 @@ 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` flag, it deletes the named <ref> after verifying it +With `-d`, it deletes the named <ref> after verifying it still contains <old-oid>. With `--stdin`, update-ref reads instructions from standard input and
-- 2.46.1.641.g54e7913fcb6
Taylor BlauRe: [PATCH 1/6] doc: update-ref: drop “flag”
On Tue, Oct 15, 2024 at 09:03:10PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name> > > The other paragraphs on options say `With <option>,`. Let’s be uniform. > > Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> > --- > Documentation/git-update-ref.txt | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt > index afcf33cf608..fe5967234e9 100644 > --- a/Documentation/git-update-ref.txt > +++ b/Documentation/git-update-ref.txt > @@ -55,7 +55,7 @@ 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` flag, it deletes the named <ref> after verifying it > +With `-d`, it deletes the named <ref> after verifying it > still contains <old-oid>.
It looks like we may want to re-wrap this paragraph after tweaking the wording on the first line.
Thanks, Taylor
Eric SunshineRe: [PATCH 1/6] doc: update-ref: drop “flag”
On Wed, Oct 16, 2024 at 4:46 PM Taylor Blau <me@ttaylorr.com> wrote:
> On Tue, Oct 15, 2024 at 09:03:10PM +0200, kristofferhaugsbakk@fastmail.com wrote: > > -With `-d` flag, it deletes the named <ref> after verifying it > > +With `-d`, it deletes the named <ref> after verifying it > > still contains <old-oid>. > > It looks like we may want to re-wrap this paragraph after tweaking the > wording on the first line.
I think we typically avoid rewrapping after minor edits like this since rewrapping introduces unnecessary noise which makes it more difficult for reviewers to identify the important (actual) change.
Taylor BlauRe: [PATCH 1/6] doc: update-ref: drop “flag”
On Wed, Oct 16, 2024 at 06:08:05PM -0400, Eric Sunshine wrote:
> On Wed, Oct 16, 2024 at 4:46 PM Taylor Blau <me@ttaylorr.com> wrote: > > On Tue, Oct 15, 2024 at 09:03:10PM +0200, kristofferhaugsbakk@fastmail.com wrote: > > > -With `-d` flag, it deletes the named <ref> after verifying it > > > +With `-d`, it deletes the named <ref> after verifying it > > > still contains <old-oid>. > > > > It looks like we may want to re-wrap this paragraph after tweaking the > > wording on the first line. > > I think we typically avoid rewrapping after minor edits like this > since rewrapping introduces unnecessary noise which makes it more > difficult for reviewers to identify the important (actual) change.
I have done it in the past myself, since I often find the result of re-wrapping much nicer to read. But I see what you are saying, and certainly don't feel strongly.
Thanks, Taylor
Re: [PATCH 1/6] doc: update-ref: drop “flag”
On Thu, Oct 17, 2024, at 00:09, Taylor Blau wrote:
> On Wed, Oct 16, 2024 at 06:08:05PM -0400, Eric Sunshine wrote: >> On Wed, Oct 16, 2024 at 4:46 PM Taylor Blau <me@ttaylorr.com> wrote: >> > On Tue, Oct 15, 2024 at 09:03:10PM +0200, kristofferhaugsbakk@fastmail.com wrote: >> > > -With `-d` flag, it deletes the named <ref> after verifying it >> > > +With `-d`, it deletes the named <ref> after verifying it >> > > still contains <old-oid>. >> > >> > It looks like we may want to re-wrap this paragraph after tweaking the >> > wording on the first line. >> >> I think we typically avoid rewrapping after minor edits like this >> since rewrapping introduces unnecessary noise which makes it more >> difficult for reviewers to identify the important (actual) change.
I was skeptical at first. But I saw that this line is only 55 characters long. So I think (like Taylor) that rewrap is in order.
What if I make a commit with just that word drop and then an immediate fixup! commit which wraps the paragraph? That way the review is still straightforward. And hopefully the integration part is not complicated further.
> > I have done it in the past myself, since I often find the result of > re-wrapping much nicer to read. But I see what you are saying, and > certainly don't feel strongly. > > Thanks, > Taylor
-- Kris
Eric SunshineRe: [PATCH 1/6] doc: update-ref: drop “flag”
On Thu, Oct 17, 2024 at 11:30 AM Kristoffer Haugsbakk <kristofferhaugsbakk@fastmail.com> wrote:
> On Thu, Oct 17, 2024, at 00:09, Taylor Blau wrote: > > On Wed, Oct 16, 2024 at 06:08:05PM -0400, Eric Sunshine wrote: > >> I think we typically avoid rewrapping after minor edits like this > >> since rewrapping introduces unnecessary noise which makes it more > >> difficult for reviewers to identify the important (actual) change. > > I was skeptical at first. But I saw that this line is only 55 > characters long. So I think (like Taylor) that rewrap is in order. > > What if I make a commit with just that word drop and then an immediate > fixup! commit which wraps the paragraph? That way the review is still > straightforward. And hopefully the integration part is not complicated > further.
Don't bother. That's even more work for yourself, for reviewers, and for the integrator, and it increases the cognitive load for everyone.
There are far fewer reviewers than there are people submitting patches to this project, so it is helpful for submitters to do what they can to make life easier for reviewers, and foregoing re-wrapping of lines, in general, is one such way to do so. However, this is such a minor change that it isn't going to matter one way or the other, especially if Taylor, as interim maintainer, is willing to accept the extra noise caused by re-wrapping.
Taylor BlauRe: [PATCH 1/6] doc: update-ref: drop “flag”
On Thu, Oct 17, 2024 at 12:31:26PM -0400, Eric Sunshine wrote:
> On Thu, Oct 17, 2024 at 11:30 AM Kristoffer Haugsbakk > <kristofferhaugsbakk@fastmail.com> wrote: > > On Thu, Oct 17, 2024, at 00:09, Taylor Blau wrote: > > > On Wed, Oct 16, 2024 at 06:08:05PM -0400, Eric Sunshine wrote: > > >> I think we typically avoid rewrapping after minor edits like this > > >> since rewrapping introduces unnecessary noise which makes it more > > >> difficult for reviewers to identify the important (actual) change. > > > > I was skeptical at first. But I saw that this line is only 55 > > characters long. So I think (like Taylor) that rewrap is in order. > > > > What if I make a commit with just that word drop and then an immediate > > fixup! commit which wraps the paragraph? That way the review is still > > straightforward. And hopefully the integration part is not complicated > > further. > > Don't bother. That's even more work for yourself, for reviewers, and > for the integrator, and it increases the cognitive load for everyone. > > There are far fewer reviewers than there are people submitting patches > to this project, so it is helpful for submitters to do what they can > to make life easier for reviewers, and foregoing re-wrapping of lines, > in general, is one such way to do so. However, this is such a minor > change that it isn't going to matter one way or the other, especially > if Taylor, as interim maintainer, is willing to accept the extra noise > caused by re-wrapping.
I agree with everything Eric wrote here. If you want to send a new round that re-wraps the text, please do so in this patch (that is, make patch 1/6 in your new round apply the changes from this version *and* rewrap the containing paragraph). Please do not send fixup! patches or other such things.
Thanks, Taylor
[PATCH 2/6] doc: update-ref: remove safety paragraphs
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). - With `-d`, it deletes the named <ref> after verifying it still contains <old-oid>.
-- 2.46.1.641.g54e7913fcb6
Taylor BlauRe: [PATCH 2/6] doc: update-ref: remove safety paragraphs
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
[PATCH 3/6] doc: update-ref: demote symlink to last section
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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 mostly of historical note at this point, not something that is needed in the main section of the documentation.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> --- Documentation/git-update-ref.txt | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index ec268b1426d..c03e65404e8 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -29,14 +29,6 @@ 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:". -More importantly, it allows the update of a ref file to follow -these symbolic pointers, whether they are symlinks or these -"regular file symbolic refs". It follows *real* symlinks only -if they start with "refs/": otherwise it will just try to read -them and update them as a regular file (i.e. it will allow the -filesystem to follow them, but will overwrite such a symlink to -somewhere else with a regular filename). - If --no-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers. @@ -185,6 +177,17 @@ An update will fail (without changing <ref>) if the current user is unable to create a new log file, append to the existing log file or does not have committer information available. +NOTES +----- + +Symbolic refs were initially implemented using symbolic links. This is +now deprecated since not all filesystems support symbolic links. + +This command follows *real* symlinks only if they start with "refs/": +otherwise it will just try to read them and update them as a regular +file (i.e. it will allow the filesystem to follow them, but will +overwrite such a symlink to somewhere else with a regular filename). + GIT --- Part of the linkgit:git[1] suite
-- 2.46.1.641.g54e7913fcb6
[PATCH 4/6] doc: update-ref: remove confusing paragraph
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
This paragraph interrupts the flow of this 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.
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).Documentation/git-update-ref.txt | 4 ---- 1 file changed, 4 deletions(-)
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index c03e65404e8..4bb3389cc7c 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.
-- 2.46.1.641.g54e7913fcb6
Taylor BlauRe: [PATCH 4/6] doc: update-ref: remove confusing paragraph
On Tue, Oct 15, 2024 at 09:03:13PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name> > > This paragraph interrupts the flow of this 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.
I think that it is worth saying that this concept is explained well throughout other parts of the documentation, including other parts of 'git-update-ref(1)', as well as the glossary content.
I don't think that you necessarily need to mention that here. But at least I was initially confused thinking that this patch proposed removing the only mention of the special "ref:" syntax for symbolic references.
But it does not, so I think that this patch as you wrote it is good. Let's keep reading...
Thanks, Taylor
Re: [PATCH 4/6] doc: update-ref: remove confusing paragraph
On Wed, Oct 16, 2024, at 22:51, Taylor Blau wrote:
> […] > > I think that it is worth saying that this concept is explained well > throughout other parts of the documentation, including other parts of > 'git-update-ref(1)', as well as the glossary content. > > I don't think that you necessarily need to mention that here. But at > least I was initially confused thinking that this patch proposed > removing the only mention of the special "ref:" syntax for symbolic > references. > > But it does not, so I think that this patch as you wrote it is good. > Let's keep reading...
You/a reader in general being in doubt is enough reason to mention some other documentation source. I’ll fix in the next version.
And thanks for reading!
Taylor BlauRe: [PATCH 4/6] doc: update-ref: remove confusing paragraph
On Wed, Oct 16, 2024 at 10:55:13PM +0200, Kristoffer Haugsbakk wrote:
> On Wed, Oct 16, 2024, at 22:51, Taylor Blau wrote: > > […] > > > > I think that it is worth saying that this concept is explained well > > throughout other parts of the documentation, including other parts of > > 'git-update-ref(1)', as well as the glossary content. > > > > I don't think that you necessarily need to mention that here. But at > > least I was initially confused thinking that this patch proposed > > removing the only mention of the special "ref:" syntax for symbolic > > references. > > > > But it does not, so I think that this patch as you wrote it is good. > > Let's keep reading... > > You/a reader in general being in doubt is enough reason to mention some > other documentation source. I’ll fix in the next version. > > And thanks for reading!
Thank you, and no problem ;-).
Thanks, Taylor
[PATCH 5/6] doc: update-ref: discuss symbolic links
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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.
This is also a good place to mention why `--stdin` has those `symref-*` commands.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> --- Documentation/git-update-ref.txt | 6 ++++++ 1 file changed, 6 insertions(+)
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 4bb3389cc7c..623c4d860eb 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -25,6 +25,12 @@ 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. +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. + If --no-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers.
-- 2.46.1.641.g54e7913fcb6
Re: [PATCH 5/6] doc: update-ref: discuss symbolic links
On Tue, Oct 15, 2024, at 21:03, kristofferhaugsbakk@fastmail.com wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name>
Tsk. Subject should have been “discuss symbolic refs”.
-- Kristoffer Haugsbakk kristofferhaugsbakk@fastmail.com
Taylor BlauRe: [PATCH 5/6] doc: update-ref: discuss symbolic links
On Tue, Oct 15, 2024 at 09:08:29PM +0200, Kristoffer Haugsbakk wrote:
> On Tue, Oct 15, 2024, at 21:03, kristofferhaugsbakk@fastmail.com wrote: > > From: Kristoffer Haugsbakk <code@khaugsbakk.name> > > Tsk. Subject should have been “discuss symbolic refs”.
Agreed.
Thanks, Taylor
[PATCH 6/6] doc: mutually link update-ref and symbolic-ref
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
These two commands are similar enough to acknowledge each other on their documentation pages.
See the previous commit where we discussed that option-less update-ref does not support updating symbolic refs but symbolic-ref does.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> --- Documentation/git-symbolic-ref.txt | 4 ++++ Documentation/git-update-ref.txt | 4 ++++ 2 files changed, 8 insertions(+)
diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 761b154bcbb..33ca381fde0 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -73,6 +73,10 @@ default. symbolic ref were printed correctly, with status 1 if the requested name is not a symbolic ref, or 128 if another error occurs. +SEE ALSO +-------- +linkgit:git-update-ref[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 623c4d860eb..fada3f670eb 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -190,6 +190,10 @@ otherwise it will just try to read them and update them as a regular file (i.e. it will allow the filesystem to follow them, but will overwrite such a symlink to somewhere else with a regular filename). +SEE ALSO +-------- +linkgit:git-symbolic-ref[1] + GIT --- Part of the linkgit:git[1] suite
-- 2.46.1.641.g54e7913fcb6
Bence FerdinandyRe: [PATCH 0/6] doc: update-ref: amend old material and discuss symrefs
On Tue Oct 15, 2024 at 21:03, <kristofferhaugsbakk@fastmail.com> wrote:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name> > > (See the previous email for the context) > > 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 (`ref: ` files… or > strings nowadays with the different formats that refs can have?) > discussion is moved > • Link update-ref to symbolic-ref and vice versa
Thanks, it seems much more clear to me this way!
Reviewed-by: Bence Ferdinandy <bence@ferdinandy.com>
Taylor BlauRe: [PATCH 0/6] doc: update-ref: amend old material and discuss symrefs
On Tue, Oct 15, 2024 at 09:03:09PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> Kristoffer Haugsbakk (6): > doc: update-ref: drop “flag” > doc: update-ref: remove safety paragraphs > doc: update-ref: demote symlink to last section > doc: update-ref: remove confusing paragraph > doc: update-ref: discuss symbolic links > doc: 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(-)
Thanks for working on this. These changes generally looked good to me (although seeing smart-quotes in the commit messages was a little surprising ;-)).
I'm making a note for the next WC report to expect a new round that corrects the subject line of the penultimate patch "doc: update-ref: discuss symbolic links".
As a general note, prefixing commits with "doc: update-ref: " is a little strange to me. I think I might have instead written:
Documentation/git-update-ref.txt: remove safety paragraphs
, and so on. I left a couple of other small notes, but I don't think any of them are urgent to address, though it would be nice.
Thanks for working on this and improving Git's documentation.
Thanks, Taylor
Re: [PATCH 0/6] doc: update-ref: amend old material and discuss symrefs
On Wed, Oct 16, 2024, at 22:54, Taylor Blau wrote:
> Thanks for working on this. These changes generally looked good to me > (although seeing smart-quotes in the commit messages was a little > surprising ;-)). > > I'm making a note for the next WC report to expect a new round that > corrects the subject line of the penultimate patch "doc: update-ref: > discuss symbolic links". > > As a general note, prefixing commits with "doc: update-ref: " is a > little strange to me. I think I might have instead written: > > Documentation/git-update-ref.txt: remove safety paragraphs > > , and so on. I left a couple of other small notes, but I don't think any > of them are urgent to address, though it would be nice. > > Thanks for working on this and improving Git's documentation. > > Thanks, > Taylor
Thanks for the review overview. I’ll change the subjects/area parts in the next round.
I looked through the commit subjects for `Documentation` in the past and, seeing several different styles, landed on one of the shorter ones. According to my recollection.
-- Kristoffer Haugsbakk
[PATCH v2 0/6] doc: update-ref: amend old material and discuss symrefs
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
[PATCH v2 1/6] Documentation/git-update-ref.txt: drop “flag”
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index afcf33cf608..fe5967234e9 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -55,7 +55,7 @@ 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` flag, it deletes the named <ref> after verifying it +With `-d`, it deletes the named <ref> after verifying it still contains <old-oid>. With `--stdin`, update-ref reads instructions from standard input and
-- 2.46.1.641.g54e7913fcb6
karthik nayakRe: [PATCH v2 1/6] Documentation/git-update-ref.txt: drop “flag”
kristofferhaugsbakk@fastmail.com writes:
> From: Kristoffer Haugsbakk <code@khaugsbakk.name> > > 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 | 2 +- > 1 file changed, 1 insertion(+), 1 deletion(-) > > diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt > index afcf33cf608..fe5967234e9 100644 > --- a/Documentation/git-update-ref.txt > +++ b/Documentation/git-update-ref.txt > @@ -55,7 +55,7 @@ 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` flag, it deletes the named <ref> after verifying it > +With `-d`, it deletes the named <ref> after verifying it > still contains <old-oid>. >
So you mean it would read nicer as s/verifying/verifying that/. Which makes sense to me, I'd have preferred that this was fixed here and the others in a follow up patch like you mentioned, but that's okay!
> With `--stdin`, update-ref reads instructions from standard input and > -- > 2.46.1.641.g54e7913fcb6
[PATCH v2 2/6] Documentation/git-update-ref.txt: remove safety paragraphs
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). - With `-d`, it deletes the named <ref> after verifying it still contains <old-oid>.
-- 2.46.1.641.g54e7913fcb6
karthik nayakRe: [PATCH v2 2/6] Documentation/git-update-ref.txt: remove safety paragraphs
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!
Re: [PATCH v2 2/6] Documentation/git-update-ref.txt: remove safety paragraphs
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)
Re: [PATCH v2 2/6] Documentation/git-update-ref.txt: remove safety paragraphs
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.
-- Kristoffer Haugsbakk
[PATCH v2 3/6] Documentation/git-update-ref.txt: demote symlink to last section
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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 mostly of historical note at this point, not something that is needed in the main section of the documentation.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> --- Documentation/git-update-ref.txt | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index ec268b1426d..c03e65404e8 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -29,14 +29,6 @@ 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:". -More importantly, it allows the update of a ref file to follow -these symbolic pointers, whether they are symlinks or these -"regular file symbolic refs". It follows *real* symlinks only -if they start with "refs/": otherwise it will just try to read -them and update them as a regular file (i.e. it will allow the -filesystem to follow them, but will overwrite such a symlink to -somewhere else with a regular filename). - If --no-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers. @@ -185,6 +177,17 @@ An update will fail (without changing <ref>) if the current user is unable to create a new log file, append to the existing log file or does not have committer information available. +NOTES +----- + +Symbolic refs were initially implemented using symbolic links. This is +now deprecated since not all filesystems support symbolic links. + +This command follows *real* symlinks only if they start with "refs/": +otherwise it will just try to read them and update them as a regular +file (i.e. it will allow the filesystem to follow them, but will +overwrite such a symlink to somewhere else with a regular filename). + GIT --- Part of the linkgit:git[1] suite
-- 2.46.1.641.g54e7913fcb6
[PATCH v2 4/6] Documentation/git-update-ref.txt: remove confusing paragraph
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 --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index c03e65404e8..4bb3389cc7c 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.
-- 2.46.1.641.g54e7913fcb6
[PATCH v2 5/6] Documentation/git-update-ref.txt: discuss symbolic refs
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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 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 linksDocumentation/git-update-ref.txt | 6 ++++++ 1 file changed, 6 insertions(+)
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 4bb3389cc7c..5866b6f2d37 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -25,6 +25,12 @@ 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. +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 `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.
-- 2.46.1.641.g54e7913fcb6
[PATCH v2 6/6] Documentation: mutually link update-ref and symbolic-ref
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
These two commands are similar enough to acknowledge each other on their documentation pages.
See the previous commit where we discussed that option-less update-ref does not support updating symbolic refs but symbolic-ref does.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> --- Documentation/git-symbolic-ref.txt | 4 ++++ Documentation/git-update-ref.txt | 4 ++++ 2 files changed, 8 insertions(+)
diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 761b154bcbb..33ca381fde0 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -73,6 +73,10 @@ default. symbolic ref were printed correctly, with status 1 if the requested name is not a symbolic ref, or 128 if another error occurs. +SEE ALSO +-------- +linkgit:git-update-ref[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 5866b6f2d37..c64d80f5a2d 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -190,6 +190,10 @@ otherwise it will just try to read them and update them as a regular file (i.e. it will allow the filesystem to follow them, but will overwrite such a symlink to somewhere else with a regular filename). +SEE ALSO +-------- +linkgit:git-symbolic-ref[1] + GIT --- Part of the linkgit:git[1] suite
-- 2.46.1.641.g54e7913fcb6
karthik nayakRe: [PATCH v2 0/6] doc: update-ref: amend old material and discuss symrefs
kristofferhaugsbakk@fastmail.com writes:
> 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 >
Thanks for working on this, I have gone through the patches, I think it is in a great state.
Karthik
[snip]
[PATCH v3 0/6] doc: update-ref: amend old material and discuss symrefs
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
[PATCH v3 1/6] Documentation/git-update-ref.txt: drop “flag”
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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
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 | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-)
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index afcf33cf608..a2bee2ea24a 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -55,7 +55,7 @@ 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` flag, 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.46.1.641.g54e7913fcb6
[PATCH v3 2/6] Documentation/git-update-ref.txt: remove safety paragraphs
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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 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.
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)
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/#tDocumentation/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 a2bee2ea24a..1a0aec041ea 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 that it still contains <old-oid>.
-- 2.46.1.641.g54e7913fcb6
[PATCH v3 3/6] Documentation/git-update-ref.txt: demote symlink to last section
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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 mostly of historical note at this point, not something that is needed in the main section of the documentation.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> --- Documentation/git-update-ref.txt | 19 +++++++++++-------- 1 file changed, 11 insertions(+), 8 deletions(-)
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 1a0aec041ea..6aaa7339d71 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -29,14 +29,6 @@ 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:". -More importantly, it allows the update of a ref file to follow -these symbolic pointers, whether they are symlinks or these -"regular file symbolic refs". It follows *real* symlinks only -if they start with "refs/": otherwise it will just try to read -them and update them as a regular file (i.e. it will allow the -filesystem to follow them, but will overwrite such a symlink to -somewhere else with a regular filename). - If --no-deref is given, <ref> itself is overwritten, rather than the result of following the symbolic pointers. @@ -185,6 +177,17 @@ An update will fail (without changing <ref>) if the current user is unable to create a new log file, append to the existing log file or does not have committer information available. +NOTES +----- + +Symbolic refs were initially implemented using symbolic links. This is +now deprecated since not all filesystems support symbolic links. + +This command follows *real* symlinks only if they start with "refs/": +otherwise it will just try to read them and update them as a regular +file (i.e. it will allow the filesystem to follow them, but will +overwrite such a symlink to somewhere else with a regular filename). + GIT --- Part of the linkgit:git[1] suite
-- 2.46.1.641.g54e7913fcb6
[PATCH v3 4/6] Documentation/git-update-ref.txt: remove confusing paragraph
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 --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.
-- 2.46.1.641.g54e7913fcb6
[PATCH v3 5/6] Documentation/git-update-ref.txt: discuss symbolic refs
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
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 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 linksDocumentation/git-update-ref.txt | 6 ++++++ 1 file changed, 6 insertions(+)
diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 61647ee8413..2e85f7ce3ee 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -25,6 +25,12 @@ 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. +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 `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.
-- 2.46.1.641.g54e7913fcb6
[PATCH v3 6/6] Documentation: mutually link update-ref and symbolic-ref
From: Kristoffer Haugsbakk <code@khaugsbakk.name>
These two commands are similar enough to acknowledge each other on their documentation pages.
See the previous commit where we discussed that option-less update-ref does not support updating symbolic refs but symbolic-ref does.
Signed-off-by: Kristoffer Haugsbakk <code@khaugsbakk.name> --- Documentation/git-symbolic-ref.txt | 4 ++++ Documentation/git-update-ref.txt | 4 ++++ 2 files changed, 8 insertions(+)
diff --git a/Documentation/git-symbolic-ref.txt b/Documentation/git-symbolic-ref.txt index 761b154bcbb..33ca381fde0 100644 --- a/Documentation/git-symbolic-ref.txt +++ b/Documentation/git-symbolic-ref.txt @@ -73,6 +73,10 @@ default. symbolic ref were printed correctly, with status 1 if the requested name is not a symbolic ref, or 128 if another error occurs. +SEE ALSO +-------- +linkgit:git-update-ref[1] + GIT --- Part of the linkgit:git[1] suite diff --git a/Documentation/git-update-ref.txt b/Documentation/git-update-ref.txt index 2e85f7ce3ee..8a4281cde9f 100644 --- a/Documentation/git-update-ref.txt +++ b/Documentation/git-update-ref.txt @@ -190,6 +190,10 @@ otherwise it will just try to read them and update them as a regular file (i.e. it will allow the filesystem to follow them, but will overwrite such a symlink to somewhere else with a regular filename). +SEE ALSO +-------- +linkgit:git-symbolic-ref[1] + GIT --- Part of the linkgit:git[1] suite
-- 2.46.1.641.g54e7913fcb6
Taylor BlauRe: [PATCH v3 0/6] doc: update-ref: amend old material and discuss symrefs
On Mon, Oct 21, 2024 at 10:47:23PM +0200, kristofferhaugsbakk@fastmail.com wrote:
> Documentation/git-symbolic-ref.txt | 4 +++ > Documentation/git-update-ref.txt | 48 +++++++++++++----------------- > 2 files changed, 25 insertions(+), 27 deletions(-)
Thanks, this version looks quite good to me. Are we ready to start merging this round down?
(I saw that Karthik had suggested that 'v2' was already looking good to them, but it would be nice to get a similar ack on this latest round).
Thanks, Taylor
Andreas SchwabRe: ref: with git update-ref?
On Okt 11 2024, Bence Ferdinandy wrote:
> the documentation for `git update-ref` has this sentence: > >> 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:".
This is about the format of the reference to be updated, not the <new-oid> argument.
See gitglossary(1):
symref
Symbolic reference: instead of containing the SHA-1 id itself, it
is of the format ref: refs/some/thing and when referenced, it
recursively dereferences to this reference. HEAD is a prime
example of a symref. Symbolic references are manipulated with the
git-symbolic-ref(1) command.-- Andreas Schwab, schwab@linux-m68k.org GPG Key fingerprint = 7578 EB47 D4E5 4D69 2510 2552 DF73 E780 A9DA AEC1 "And now for something completely different."