[PATCH 0/3] Clarify pseudo-ref terminology

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(-)