Re: [PATCH v2 1/5] doc: glossary: add root ref and clarify pseudorefs

From: Junio C Hamano <gitster@pobox.com>
Date: Nov 3, 2026, 18:30 UTC
Message-ID: <xmqqecd1939a.fsf@gitster.g>
In-Reply-To: <aunFqykTV0QHCmV3@pks.im>

Patrick Steinhardt <ps@pks.im> writes:

Show 12 quoted lines

> I'm still not entirely convinced by this change, as it only focusses on
> the difference in storage. How about this instead:
>
>     [[def_pseudoref]]pseudoref::
>         A name that can be used like a <<def_ref,ref>> to refer to an
>         <<def_object,object>>, but that has different semantics: it can
>         record more than one object ID and may carry additional metadata.
>         In contrast to root refs, pseudorefs are therefore not stored or
>         handled by the ref backend. They can be passed to commands like
>         linkgit:git-log[1] or linkgit:git-diff[1], but cannot be written
>         by linkgit:git-update-ref[1] or listed by
>         linkgit:git-for-each-ref[1].

Between the two I would prefer yours. I would replace "different" with "additional", because a pseudoref can be used as the name of the first object it contains in a fully compatible way as any other refs, I want to avoid "different" that implies "there are additional things it can do but there are things it cannot do" Venn diagram.

Then replace "carry additional" with "carry extra", just to avoid repetitions of "additional" due to the earlier change.