From: Andy Koppe <andy.koppe@gmail.com>
Date: Sun, 01 Nov 2026 23:26:04 GMT
Subject: Re: [PATCH 2/5] doc: glossary: update per-worktree refs
Message-ID: <CAHWeT-be9+8vpjmj=NVYK3rjG5MrBqmSwuX+jJvvUhkKwvKF2w@mail.gmail.com>
In-Reply-To: <atsPvF6wVdugtwrH@pks.im>

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

Done in v2.

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

It's difficult, because pseudorefs are per-worktree, but they aren't
refs. I thought they should still be mentioned under "per-worktree
refs", without calling them refs.

> I wonder whether we should simply refer to
> that section without naming any examples.

Good idea. Done in v2.

Andy