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

[Patrick Steinhardt <ps@pks.im>]

On Thu, Oct 22, 2026 at 10:28:49PM +0100, Andy Koppe wrote:
> 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.

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

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

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