From: Patrick Steinhardt <ps@pks.im>
Date: Fri, 23 Oct 2026 07:41:48 GMT
Subject: Re: [PATCH 2/5] doc: glossary: update per-worktree refs
Message-ID: <atsPvF6wVdugtwrH@pks.im>
In-Reply-To: <20261022212903.177261-3-andy.koppe@gmail.com>

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. I wonder whether we should simply refer to
that section without naming any examples.

Patrick