Re: [PATCH 0/5] root refs vs pseudorefs

From: Julia Evans <julia@jvns.ca>
Date: Oct 23, 2026, 13:21 UTC
Message-ID: <93D20D7C-E19B-4A41-AC10-4AFC8330E844@jvns.ca>
In-Reply-To: <20261022212903.177261-1-andy.koppe@gmail.com>

Show 23 quoted lines

> On Oct 22, 2026, at 5:28 PM, Andy Koppe <andy.koppe@gmail.com> wrote:
> 
> Since 993d57eded (refs: pseudorefs are no refs, 2024-05-15), the term
> "pseudoref" has been restricted to FETCH_HEAD and MERGE_HEAD, which are
> not stored in the ref backends, while other refs outside of "refs/",
> such as HEAD and ORIG_HEAD, are called root refs. However, a fair number
> of docs, comments, messages and tests still use "pseudoref" in its old
> sense. And while the glossary describes the rules for refs in the root
> of the hierarchy, it does not explicitly define the term, even though
> "git for-each-ref --include-root-refs" uses it.
> 
> This series adds a "root ref" entry to the glossary and clarifies the
> "pseudoref" entry, and then replaces the outdated uses of "pseudoref" in
> docs, code and tests. While at it, it also updates the long outdated
> glossary entry for per-worktree refs, and fixes a few inaccuracies
> found along the way, for example about which refs get a reflog in
> git-update-ref(1) and core.logAllRefUpdates.
> 
> I've left __git_pseudoref_exists() in the completion script alone apart
> from its comment, even though it's used for both pseudorefs and root
> refs. It could be renamed, keeping the old name as a deprecated wrapper
> like elsewhere in the script, but it's not obvious what to, because
> there is no term covering both.

Show 14 quoted lines

> Andy Koppe (5):
>  doc: glossary: add root ref and clarify pseudorefs
>  doc: glossary: update per-worktree refs
>  doc: stop calling root refs pseudorefs
>  refs: stop calling root refs pseudorefs
>  t: stop calling root refs pseudorefs
> 
> Documentation/config/core.adoc                |  2 +-
> Documentation/for-each-ref-options.adoc       |  2 +-
> Documentation/git-ls-remote.adoc              |  4 +-
> Documentation/git-update-ref.adoc             | 13 ++-
> Documentation/git-worktree.adoc               |  9 +-
> Documentation/glossary-content.adoc           | 86 ++++++++++++-------
> Documentation/rev-list-options.adoc           |  4 +-

I wonder if gitdatamodel.adoc should also cover pseudorefs and root refs in the “References” section. Right now it only says something extremely short on the topic:

  Git may also create references other than HEAD at the base of
  the hierarchy, like ORIG_HEAD.

Show 23 quoted lines

> builtin/for-each-ref.c                        |  2 +-
> contrib/completion/git-completion.bash        |  7 +-
> refs.h                                        | 13 ++-
> revision.c                                    |  2 +-
> t/show-ref-exists-tests.sh                    |  4 +-
> t/t0600-reffiles-backend.sh                   |  2 +-
> t/t0610-reftable-basics.sh                    |  2 +-
> t/t1400-update-ref.sh                         | 66 +++++++-------
> t/t1403-show-ref.sh                           |  2 +-
> t/t1460-refs-migrate.sh                       |  4 +-
> t/t4013-diff-various.sh                       |  6 +-
> ...iff.diff-tree_--cc_--summary_REVERSE_HEAD} |  2 +-
> t/t6302-for-each-ref-filter.sh                |  4 +-
> t/t9902-completion.sh                         |  4 +-
> 21 files changed, 129 insertions(+), 111 deletions(-)
> rename t/t4013/{diff.diff-tree_--cc_--summary_REVERSE => diff.diff-tree_--cc_--summary_REVERSE_HEAD} (73%)
> 
> 
> base-commit: 7e34d8174dcda3435d1404c9a30bef46afe6c13e
> -- 
> 2.56.0
> 
>