# Glossary gains "root ref" entry as pseudoref wording is cleaned up across docs and code

_Since 2024 "pseudoref" has meant only FETCH_HEAD and MERGE_HEAD, but many docs, messages and tests still use the old meaning._

Section: Project. Edition of 2026-11-13. Written by an AI editor from the thread "[PATCH 0/5] root refs vs pseudorefs" (55 messages): https://gitlist.dev/t/66636

Since 993d57eded (refs: pseudorefs are no refs, 2024-05-15), "pseudoref" has been limited to FETCH_HEAD and MERGE_HEAD, which the ref backends do not store. Other refs outside refs/, such as HEAD and ORIG_HEAD, are called root refs. Andy Koppe's series notes that many docs, comments, messages and tests still use the old sense, and that the glossary never defined "root ref" even though `git for-each-ref --include-root-refs` uses it.

The series adds a glossary entry, moving the naming rules and the list of irregular root refs there from the "ref" entry, and rewords the "pseudoref" entry. It also updates the "per-worktree ref" entry. That entry was out of date since a9be29c981: all root refs are per-worktree, as are refs under refs/worktree/ and refs/rewritten/. It now says the list will not be extended, since new per-worktree refs are meant to go under refs/worktree/.

Other patches update manual pages, with git-worktree(1) saying both root refs and pseudorefs are per-worktree and git-ls-remote(1) saying HEAD and refs under refs/ are shown by default. They also update messages and comments in the code and test titles. The "--merge" error message now says an ongoing merge, cherry-pick, revert or rebase is required instead of listing names. In t1400 and t4013 the test refs are renamed to ROOT_REF_HEAD and REVERSE_HEAD. The bash completion function __git_pseudoref_exists() is not renamed, because there is no obvious term covering both root refs and pseudorefs.

Junio Hamano said that comparing against the previous version, everything looked sensible. Koppe replied that he took Junio's suggestions on the ls-remote wording and on the glossary examples, which now mention remote-tracking branches alongside local branches and tags. Junio also noted that the naming rules for root refs are incompletely enforced; that is considered a separate topic.
