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

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

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

> Reword the "pseudoref" entry so that it no longer calls them refs,

Very very good.  They are "pseudo" and are *not* "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 has additional semantics: it can
> +	record more than one object ID and may carry extra metadata.

Good.

> +	... In
> +	contrast to <<def_root_ref,root refs>>, pseudorefs are therefore
> +	not stored or handled by the ref backend.

I am not sure if we need to contrast this with root refs, though.
Normal refs are also handled by the ref backend after all, but we do
not contrast pseudorefs with them, either.

Can we get rid of "In contrast to ..., " and start the sentence with
"Therefore, pseudorefs are not..."?

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

Do we want to mention remotes and notes hierarchies, I wonder.
If we do not mention remotes, calling things in refs/heads
specifically "local" branches is not very useful.

> +[[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`
> +--

Good.

> +<<def_pseudoref,Pseudorefs>> are not considered root refs, even though
> +they follow the naming rules.

Again, I am not sure what the value of saying this is.  It somehow
feels like elephants are not rhinos even though they are both gray.
Why should a confused reader expect it to be considered root refs?
We already said that pseudorefs are not even refs upfront.

Other than these "do not contrast pseudorefs with refs or root refs"
suggestions on two places, the patch looks ready to me.

Thanks.


This is a tangent but is very deeply related to how "root refs" are
handled by the code, so I'll mention it.  Random things outside refs/
are usable as if they are refs in the same code path that handles
the root refs.  E.g.,

    $ git update-ref out/mister refs/heads/master
    $ git for-each-ref ;# not shown just like root refs
    29f5d436870d37a2e36388e96e9175e0a5bf53e9 commit	refs/heads/master
    $ ls -l .git/out/mister
    -rw------- 1 gitster gitster 41 Nov  6 14:01 .git/refo/heads/mister
    $ git show --oneline -s out/mister
    eddc71c initial

We probably should tighten the system to forbid them, not just from
creation side by tightening update-ref but from blind application of
the first element of rev_parse_rules[].

In other words, things "outside `refs/`" that are not at the root
level should not be treated by the code as if they were.

As solving this (or leaving it unsolved) has no impact on the status
of this patch we are discussing, I'll just leave #leftoverbits mark
here.