ref: with git update-ref?

ref: with git update-ref?

[Bence Ferdinandy]

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

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?

[Kristoffer Haugsbakk]

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)

Re: with git update-ref?

[Bence Ferdinandy]

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

Re: with git update-ref?

[Junio C Hamano]

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

Re: ref: with git update-ref?

[Andreas Schwab]

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

Re: with git update-ref?

[Bence Ferdinandy]

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?

[Phillip Wood]

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?

[Kristoffer Haugsbakk]

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

Re: with git update-ref?

[karthik nayak]

[-- Attachment #1: Type: text/plain, Size: 1555 bytes --]

"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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: with git update-ref?

[Kristoffer Haugsbakk]

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.

Re: with git update-ref?

[Bence Ferdinandy]

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?

[Kristoffer Haugsbakk]

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

[kristofferhaugsbakk]

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”

[kristofferhaugsbakk]

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

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

[kristofferhaugsbakk]

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

[PATCH 3/6] doc: update-ref: demote symlink to last section

[kristofferhaugsbakk]

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

[kristofferhaugsbakk]

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

[PATCH 5/6] doc: update-ref: discuss symbolic links

[kristofferhaugsbakk]

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

[PATCH 6/6] doc: mutually link update-ref and symbolic-ref

[kristofferhaugsbakk]

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

Re: [PATCH 5/6] doc: update-ref: discuss symbolic links

[Kristoffer Haugsbakk]

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

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

[Bence Ferdinandy]

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>

Re: [PATCH 1/6] doc: update-ref: drop “flag”

[Taylor Blau]

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

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

[Taylor Blau]

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

Re: [PATCH 4/6] doc: update-ref: remove confusing paragraph

[Taylor Blau]

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 5/6] doc: update-ref: discuss symbolic links

[Taylor Blau]

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

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

[Taylor Blau]

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 4/6] doc: update-ref: remove confusing paragraph

[Kristoffer Haugsbakk]

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!

Re: [PATCH 4/6] doc: update-ref: remove confusing paragraph

[Taylor Blau]

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

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

[Kristoffer Haugsbakk]

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

Re: [PATCH 1/6] doc: update-ref: drop “flag”

[Eric Sunshine]

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.

Re: [PATCH 1/6] doc: update-ref: drop “flag”

[Taylor Blau]

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”

[Kristoffer Haugsbakk]

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

Re: [PATCH 1/6] doc: update-ref: drop “flag”

[Eric Sunshine]

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.

Re: [PATCH 1/6] doc: update-ref: drop “flag”

[Taylor Blau]

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 v2 0/6] doc: update-ref: amend old material and discuss symrefs

[kristofferhaugsbakk]

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”

[kristofferhaugsbakk]

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

[PATCH v2 2/6] Documentation/git-update-ref.txt: remove safety paragraphs

[kristofferhaugsbakk]

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

[PATCH v2 3/6] Documentation/git-update-ref.txt: demote symlink to last section

[kristofferhaugsbakk]

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

[kristofferhaugsbakk]

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

[kristofferhaugsbakk]

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 links

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

[kristofferhaugsbakk]

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

Re: [PATCH v2 1/6] Documentation/git-update-ref.txt: drop “flag”

[karthik nayak]

[-- Attachment #1: Type: text/plain, Size: 1609 bytes --]

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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [PATCH v2 2/6] Documentation/git-update-ref.txt: remove safety paragraphs

[karthik nayak]

[-- Attachment #1: Type: text/plain, Size: 2347 bytes --]

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!

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

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

[karthik nayak]

[-- Attachment #1: Type: text/plain, Size: 841 bytes --]

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]

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 690 bytes --]

Re: [PATCH v2 2/6] Documentation/git-update-ref.txt: remove safety paragraphs

[Kristoffer Haugsbakk]

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

[Kristoffer Haugsbakk]

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 v3 0/6] doc: update-ref: amend old material and discuss symrefs

[kristofferhaugsbakk]

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”

[kristofferhaugsbakk]

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

[kristofferhaugsbakk]

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/#t

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

[kristofferhaugsbakk]

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

[kristofferhaugsbakk]

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

[kristofferhaugsbakk]

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 links

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

[kristofferhaugsbakk]

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

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

[Taylor Blau]

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