From: Patrick Steinhardt <ps@pks.im>
Date: Tue, 03 Nov 2026 11:29:47 GMT
Subject: Re: [PATCH v2 1/5] doc: glossary: add root ref and clarify pseudorefs
Message-ID: <aunFqykTV0QHCmV3@pks.im>
In-Reply-To: <20261101230326.3675597-2-andy.koppe@gmail.com>

On Sun, Nov 01, 2026 at 11:03:19PM +0000, Andy Koppe wrote:
> diff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc
> index 52301a56dd..f905b4467b 100644
> --- a/Documentation/glossary-content.adoc
> +++ b/Documentation/glossary-content.adoc
> @@ -500,18 +500,25 @@ exclude;;
>  	unusual refs.
>  
>  [[def_pseudoref]]pseudoref::
> -	A ref that has different semantics than normal refs. These refs can be
> -	read via normal Git commands, but cannot be written to by commands like
> -	linkgit:git-update-ref[1].
> +	A name that can be used like a <<def_ref,ref>> to refer to an
> +	<<def_object,object>>, but that is not stored in the same way as refs.
> +	For example, pseudorefs can be passed to linkgit:git-log[1] or
> +	linkgit:git-diff[1], but they cannot be written by
> +	linkgit:git-update-ref[1] or listed by linkgit:git-for-each-ref[1].

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

Patrick