From: Andy Koppe <andy.koppe@gmail.com>
Date: Sun, 01 Nov 2026 23:18:45 GMT
Subject: Re: [PATCH 1/5] doc: glossary: add root ref and clarify pseudorefs
Message-ID: <CAHWeT-aC9D0Oa0pR00rKeHNpMqfWhY5-vicASHwPRZn+J7vWaQ@mail.gmail.com>
In-Reply-To: <atsPsFnb5mrneAMb@pks.im>

On Fri, 23 Oct 2026 at 08:41, Patrick Steinhardt <ps@pks.im> wrote:
> 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.

Instead of saying that they are different, I tried to describe how
they are different . But, yep, I struggled a bit with that.

In v2, I have added git-log and git-diff as examples of where
pseudorefs can be used like references.

Thanks,
Andy