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?

quoted

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.