[0/3] Clarify pseudo-ref terminology

Message

Patrick Steinhardt April 29, 2024, 1:41 p.m. UTC

Hi,

there is quite some confusion around what is a pseudo ref and what is a
special ref, and the documentation in gitglossary(7) overlaps. This
patch series clarifies that:

  - A pseudo ref is anything in the root directory that conforms to the
    pseudo ref syntax (all uppercase, must end with _HEAD), except for
    special refs. There are some exceptions that are now listed
    explicitly, and these only exist due to historic reasons.

  - Special refs are really only either FETCH_HEAD or MERGE_HEAD, where
    the reason is that those aren't really refs, but can sometimes be
    used as such.

I was very much pressed to go a completely different way: drop the
special ref term again that we have recently introduced and replace the
pseudo ref term with it. This would return pseudo refs to their original
meaning, namely something that is not a ref, but behaves like one at
times.

The current class of pseudo refs I would then drop completely -- in my
opinion there is just no need for it. Everything should be a ref, and
what we currently call pseudo refs (things in the root hierarchy) is
really just a naming policy. Refs must either have pseudoref syntax or
they must start with "refs/". It doesn't help in my opinion that we give
refs which conform to that naming policy but happen to live in the root
directory a separate name. They behave no different than a normal ref
anyway: they are stored in the refdb and can be read and written as any
other ref starting with "refs/".

So, if we went down that road, we would:

  - Not have special refs anymore.

  - Have two pseudo refs, FETCH_HEAD and MERGE_HEAD. There is no other
    pseudo ref.

  - Clarify that refs must either start with "refs/", or have an
    all-uppercase name ending with "_HEAD". Exceptions to this rule are
    "HEAD" and a couple of others that we wrote due to historic reasons.
    All refs that match these rules behave the same, there is no
    difference between root refs and refs living in "refs/".

I think that this would be quite a lot easier to understand than the
current state of affairs we have, and also return us to the original
meaning of pseudorefs.

If people agree with that line of thought I'll happily revise this patch
series. I didn't do that yet because it would be quite a lot more work,
so I first wanted to get some buy-in.

Patrick

Patrick Steinhardt (3):
  refs: move `is_special_ref()`
  refs: do not label special refs as pseudo refs
  refs: fix segfault in `is_pseudoref()` when ref cannot be resolved

 Documentation/glossary-content.txt | 36 +++++++------
 refs.c                             | 81 ++++++++++++++----------------
 t/t6302-for-each-ref-filter.sh     | 17 +++++++
 3 files changed, 76 insertions(+), 58 deletions(-)