From: Julia Evans Date: Fri, 23 Oct 2026 13:21:11 GMT Subject: Re: [PATCH 0/5] root refs vs pseudorefs Message-ID: <93D20D7C-E19B-4A41-AC10-4AFC8330E844@jvns.ca> In-Reply-To: <20261022212903.177261-1-andy.koppe@gmail.com> > On Oct 22, 2026, at 5:28 PM, Andy Koppe 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. > 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. > 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 > >