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

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