Re: [PATCH 2/5] doc: glossary: update per-worktree refs

> On Thu, Oct 22, 2026 at 10:28:50PM +0100, Andy Koppe wrote:
> > diff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc
> > index b2c582254b..eff6d23215 100644
> > --- a/Documentation/glossary-content.adoc
> > +++ b/Documentation/glossary-content.adoc
> > @@ -494,10 +494,16 @@ exclude;;
> >       interface than the <<def_plumbing,plumbing>>.
> >
> >  [[def_per_worktree_ref]]per-worktree ref::
> > -     Refs that are per-<<def_worktree,worktree>>, rather than
> > -     global.  This is presently only <<def_HEAD,HEAD>> and any refs
> > -     that start with `refs/bisect/`, but might later include other
> > -     unusual refs.
> > +     A <<def_ref,ref>> that is specific to a <<def_worktree,worktree>>,
> > +     rather than shared between all worktrees. All
> > +     <<def_root_ref,root refs>>, such as <<def_HEAD,HEAD>>, are
> > +     per-worktree, as are refs that start with `refs/bisect/`,
> > +     `refs/worktree/` or `refs/rewritten/`.
> > ++
> > +<<def_pseudoref,Pseudorefs>> are also specific to each worktree.
>
> Should we maybe also turn this into an itemized list? Makes it easier to
> see at a glance which rrefs are per-worktree, and it becomes easier to
> extend going forward.

> > +See "REFS" in linkgit:git-worktree[1] for how to access the
> > +per-worktree refs of other worktrees.
> >
> >  [[def_pseudoref]]pseudoref::
> >       A name that can be used like a <<def_ref,ref>> to refer to
> > @@ -788,5 +794,5 @@ and pseudorefs.
> >       "working tree" and repository metadata, most of which are
> >       shared among other worktrees of a single repository, and
> >       some of which are maintained separately per worktree
> > -     (e.g. the index, HEAD and pseudorefs like MERGE_HEAD,
> > -     per-worktree refs and per-worktree configuration file).
> > +     (e.g. the index, per-worktree refs such as HEAD, pseudorefs
> > +     such as MERGE_HEAD, and the per-worktree configuration file).
>
> This is a bit curious as you distinguish between per-worktree refs and
> pseudorefs, even though you mention both of them as part of the
> per-worktree ref section.