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

From: Patrick Steinhardt <ps@pks.im>
Date: Oct 23, 2026, 07:41 UTC
Message-ID: <atsPsFnb5mrneAMb@pks.im>
In-Reply-To: <20261022212903.177261-2-andy.koppe@gmail.com>

On Thu, Oct 22, 2026 at 10:28:49PM +0100, Andy Koppe wrote:

Show 15 quoted lines

> diff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc
> index 52301a56dd..b2c582254b 100644
> --- a/Documentation/glossary-content.adoc
> +++ b/Documentation/glossary-content.adoc
> @@ -500,9 +500,10 @@ 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
> +	<<def_object,objects>>, but that is not stored in the same way as refs.
> +	For example, pseudorefs cannot be written by linkgit:git-update-ref[1]
> +	or listed by linkgit:git-for-each-ref[1].

As Junio already mentioned, I think we should retain the information about different semantics.

I also think that the previous guidance around how pseudorefs can be used is weakened, because now you only list examples of how they cannot be used. Previously though we explicitly specified that the only supported operation is reading the refs directly. So instead of giving examples of how they cannot be used, I think we should continue to list the few operations that _are_ possible.

Show 7 quoted lines

> @@ -512,6 +513,9 @@ The following pseudorefs are known to Git:
>  
>   - `MERGE_HEAD` is written by linkgit:git-merge[1] when resolving merge
>     conflicts. It contains all commit IDs which are being merged.
> ++
> +When a pseudoref contains more than one object ID, using it to refer to an
> +object yields the first one.

This is indeed a good addition.

Show 5 quoted lines

> @@ -640,6 +623,37 @@ format. See linkgit:git-reflog[1] for details.
>  	To throw away part of the development, i.e. to assign the
>  	<<def_head,head>> to an earlier <<def_revision,revision>>.
>  
> +[[def_root_ref]]root ref::

And splitting this out makes sense, as well.

Show 11 quoted lines

> +	A <<def_ref,ref>> located in the root of the ref hierarchy, outside
> +	`refs/`. Root ref names must follow these rules:
> ++
> +--
> + - The name consists of only upper-case characters or underscores.
> +
> + - The name ends with "`_HEAD`" or is equal to "`HEAD`".
> +--
> ++
> +The following irregular root refs are exceptions to these rules. This
> +list is exhaustive and shall not be extended in future:

Okay, this paragraph has been shortened a bit, which I think is a good change.

Thanks!

Patrick