git/list[1] front-page[2] threads[3] people[4] search[5] about
 

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

From
Patrick Steinhardt <ps@pks.im>
Date
Oct 23, 2026, 07:41 UTC
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:
Show 19 quoted lines
> 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.

Show 13 quoted lines
> +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
Previous: Andy KoppeNext: Andy Koppe
Message 6 of 13 in “root refs vs pseudorefs”
  1. 0/5 root refs vs pseudorefsAndy Koppe, Oct 22, 2026
  2. 1/5 doc: glossary: add root ref and clarify pseudorefsAndy Koppe, Oct 22, 2026
  3. Junio C HamanoOct 22, 2026
  4. Patrick SteinhardtOct 23, 2026
  5. 2/5 doc: glossary: update per-worktree refsAndy Koppe, Oct 22, 2026
  6. Patrick SteinhardtOct 23, 2026
  7. 3/5 doc: stop calling root refs pseudorefsAndy Koppe, Oct 22, 2026
  8. Patrick SteinhardtOct 23, 2026
  9. 4/5 refs: stop calling root refs pseudorefsAndy Koppe, Oct 22, 2026
  10. Patrick SteinhardtOct 23, 2026
  11. 5/5 t: stop calling root refs pseudorefsAndy Koppe, Oct 22, 2026
  12. Junio C HamanoOct 22, 2026
  13. Julia EvansOct 23, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.