Re: [PATCH 1/5] doc: glossary: add root ref and clarify pseudorefs

[Junio C Hamano <gitster@pobox.com>]

Andy Koppe <andy.koppe@gmail.com> writes:

> 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 | 68 +++++++++++++++++------------
>  1 file changed, 41 insertions(+), 27 deletions(-)
>
> diff --git a/Documentation/glossary-content.adoc b/Documentation/glossary-content.adoc
> index 52301a56dd..b2c582254b 100644
> --- a/Documentation/glossary-content.adoc
> +++ b/Documentation/glossary-content.adoc
> @@ -500,9 +500,10 @@ 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
> +	<<def_object,objects>>, but that is not stored in the same way as refs.
> +	For example, pseudorefs cannot be written by linkgit:git-update-ref[1]
> +	or listed by linkgit:git-for-each-ref[1].

I would love to get input from Patrick who wrote 993d57eded (refs:
pseudorefs are no refs, 2024-05-15), as I consider that the loss of
"different semantics" from this description is a rather serious one.
FETCH_HEAD and MERGE_HEAD cannot be written with update-ref simply
because it is normal for them to record multiple object names, so it
is not just "how" they are stored, but also "what" they can store,
that makes them "strange", "pseudo", "different", and "special".

>  The following pseudorefs are known to Git:
>  
> @@ -512,6 +513,9 @@ The following pseudorefs are known to Git:
>  
>   - `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.

This is an important addition.

> @@ -562,33 +566,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, 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 +623,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.

I think this is a great reorganization to split out the "these are
exceptions" into its own section.