From: Andy Koppe <andy.koppe@gmail.com>
Date: Sun, 01 Nov 2026 23:03:19 GMT
Subject: [PATCH v2 1/5] doc: glossary: add root ref and clarify pseudorefs
Message-ID: <20261101230326.3675597-2-andy.koppe@gmail.com>
In-Reply-To: <20261022212903.177261-1-andy.koppe@gmail.com>

The glossary describes refs in the root of the ref hierarchy, but does
not actually name them "root refs", even though the term is used
elsewhere, for example by "git for-each-ref --include-root-refs". It
also defines pseudorefs as refs, yet is_root_ref() deliberately excludes
them, as they are not stored or handled by the ref backends.

Add a "root ref" entry, moving the naming rules and the list of
irregular root refs there from the "ref" entry. State that pseudorefs
are not root refs, and refer to gitrevisions(7) for descriptions of
commonly used root refs and pseudorefs.

Reword the "pseudoref" entry so that it no longer calls them refs, add
git-for-each-ref(1) as another example of how they are not proper refs,
and explain that using a pseudoref containing multiple object IDs yields
the first one.

Signed-off-by: Andy Koppe <andy.koppe@gmail.com>
---
 Documentation/glossary-content.adoc | 73 ++++++++++++++++++-----------
 1 file changed, 45 insertions(+), 28 deletions(-)

diff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc
index 52301a56dd..f905b4467b 100644
--- a/Documentation/glossary-content.adoc
+++ b/Documentation/glossary-content.adoc
@@ -500,18 +500,25 @@ exclude;;
 	unusual refs.
 
 [[def_pseudoref]]pseudoref::
-	A ref that has different semantics than normal refs. These refs can be
-	read via normal Git commands, but cannot be written to by commands like
-	linkgit:git-update-ref[1].
+	A name that can be used like a <<def_ref,ref>> to refer to an
+	<<def_object,object>>, but that is not stored in the same way as refs.
+	For example, pseudorefs can be passed to linkgit:git-log[1] or
+	linkgit:git-diff[1], but they cannot be written by
+	linkgit:git-update-ref[1] or listed by linkgit:git-for-each-ref[1].
 +
 The following pseudorefs are known to Git:
-
++
+--
  - `FETCH_HEAD` is written by linkgit:git-fetch[1] or linkgit:git-pull[1]. It
    may refer to multiple object IDs. Each object ID is annotated with metadata
    indicating where it was fetched from and its fetch status.
 
  - `MERGE_HEAD` is written by linkgit:git-merge[1] when resolving merge
    conflicts. It contains all commit IDs which are being merged.
+--
++
+When a pseudoref contains more than one object ID, using it to refer to an
+object yields the first one.
 
 [[def_pull]]pull::
 	Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and
@@ -562,33 +569,12 @@ The following pseudorefs are known to Git:
 +
 The ref namespace is hierarchical.
 Ref names must either start with `refs/` or be located in the root of
-the hierarchy. For the latter, their name must follow these rules:
-+
---
- - The name consists of only upper-case characters or underscores.
-
- - The name ends with "`_HEAD`" or is equal to "`HEAD`".
---
-+
-There are some irregular refs in the root of the hierarchy that do not
-match these rules. The following list is exhaustive and shall not be
-extended in the future:
-+
---
- - `AUTO_MERGE`
-
- - `BISECT_EXPECTED_REV`
-
- - `NOTES_MERGE_PARTIAL`
-
- - `NOTES_MERGE_REF`
-
- - `MERGE_AUTOSTASH`
---
+the hierarchy, in which case they must follow the naming rules for
+<<def_root_ref,root refs>>.
 +
 Different subhierarchies are used for different purposes. For example,
 the `refs/heads/` hierarchy is used to represent local branches whereas
-the `refs/tags/` hierarchy is used to represent local tags..
+the `refs/tags/` hierarchy is used to represent local tags.
 +
 See also "REFERENCES" in linkgit:gitdatamodel[7].
 
@@ -640,6 +626,37 @@ format. See linkgit:git-reflog[1] for details.
 	To throw away part of the development, i.e. to assign the
 	<<def_head,head>> to an earlier <<def_revision,revision>>.
 
+[[def_root_ref]]root ref::
+	A <<def_ref,ref>> located in the root of the ref hierarchy, outside
+	`refs/`. Root ref names must follow these rules:
++
+--
+ - The name consists of only upper-case characters or underscores.
+
+ - The name ends with "`_HEAD`" or is equal to "`HEAD`".
+--
++
+The following irregular root refs are exceptions to these rules. This
+list is exhaustive and shall not be extended in future:
++
+--
+ - `AUTO_MERGE`
+
+ - `BISECT_EXPECTED_REV`
+
+ - `NOTES_MERGE_PARTIAL`
+
+ - `NOTES_MERGE_REF`
+
+ - `MERGE_AUTOSTASH`
+--
++
+<<def_pseudoref,Pseudorefs>> are not considered root refs, even though
+they follow the naming rules.
++
+See linkgit:gitrevisions[7] for descriptions of commonly used root refs
+and pseudorefs.
+
 [[def_SCM]]SCM::
 	Source code management (tool).
 
-- 
2.56.0