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

> 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].

>  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.

> @@ -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.