Re: [PATCH v2 01/10] Documentation/glossary: redefine pseudorefs as special refs

Justin Tobler
2024-04-30T17:18:37Z

On 24/04/30 02:26PM, Patrick Steinhardt wrote:
> Nowadays, Git knows about three different kinds of refs. As defined in
> gitglossary(7):
>
> - Regular refs that start with "refs/", like "refs/heads/main".
>
> - Pseudorefs, which live in the root directory. These must have
> all-caps names and must be a file that start with an object hash.
> Consequently, symbolic refs are not pseudorefs because they do not
> start with an object hash.
>
> - Special refs, of which we only have "FETCH_HEAD" and "MERGE_HEAD".
>
> This state is extremely confusing, and I would claim that most folks
> don't fully understand what is what here. The current definitions also
> have several problems:
>
> - Where does "HEAD" fit in? It's not a pseudoref because it can be
> a symbolic ref. It's not a regular ref because it does not start
> with "refs/". And it's not a special ref, either.
>
> - There is a strong overlap between pseudorefs and special refs. The
> pseudoref section for example mentions "MERGE_HEAD", even though it
> is a special ref. Is it thus both a pseudoref and a special ref?
>
> - Why do we even need to distinguish refs that live in the root from
> other refs when they behave just like a regular ref anyway?
>
> In other words, the current state is quite a mess and leads to wild
> inconsistencies without much of a good reason.
>
> The original reason why pseudorefs were introduced is that there are
> some refs that sometimes behave like a ref, even though they aren't a
> ref. And we really only have two of these nowadads, namely "MERGE_HEAD"

s/nowadads/nowadays/

-Justin