[PATCH v2 00/10] Clarify pseudo-ref terminology

Patrick Steinhardt
2024-04-30T12:26:26Z

[-- Attachment #1: Type: text/plain, Size: 2969 bytes --]

Hi,

this is the second version of my patch series that tries to clarify the
pseudoref terminology.

As I have alluded to in my first version of this patch series, I'd
really like to return the pseudoref terminology back to its original
roots. Namely, a pseudoref is not a ref and does not conform to the
format of refs as they may contain additional metadata. With the new
definition, we really only have two pseudorefs: FETCH_HEAD and
MERGE_HEAD.

This has multiple consequences:

- Pseudorefs are never stored via the ref backend.

- Pseudorefs can be read via tools like git-rev-parse(1).

- Pseudorefs are not surfaced by tools like git-for-each-ref(1). They
are not refs, so a tool that goes through all refs should not
surface them.

- Pseudorefs cannot be written via tools like git-update-ref(1). They
are always written by the respective subsystems that create them via
the filesystem directly.

- All other refs in the root hierarchy are just plain refs. They are
not special. They can be symbolic or regular refs. The only thing of
notice here is a bunch of restrictions that they have in place
regarding their naming.

- Special refs are no more. Or rather, special refs are the new
pseudorefs.

Overall, this significantly simplifies our whole terminology around
refs that most people didn't really understand in the first place,
including myself. Furthermore, it makes it so that the ref backends
don't need to know about any policy except for what is a proper ref
name. Whether refs should be symbolic or direct refs is higher-level
logic that belongs in the respective subsystems, and the ref backends
should not stand in the way as generic vessels for refs.

This patch series makes the necessary changes to out glossary as well as
the code.

Patrick

Patrick Steinhardt (10):
Documentation/glossary: redefine pseudorefs as special refs
Documentation/glossary: clarify limitations of pseudorefs
Documentation/glossary: define root refs as refs
refs: rename `is_pseudoref()` to `is_root_ref()`
refs: refname `is_special_ref()` to `is_pseudo_ref()`
refs: classify HEAD as a root ref
refs: root refs can be symbolic refs
refs: pseudorefs are no refs
ref-filter: properly distinuish pseudo and root refs
refs: refuse to write pseudorefs

Documentation/glossary-content.txt | 75 +++++++++---------
builtin/for-each-ref.c | 2 +-
ref-filter.c | 16 ++--
ref-filter.h | 4 +-
refs.c | 120 ++++++++++++++++-------------
refs.h | 50 +++++++++++-
refs/files-backend.c | 3 +-
refs/reftable-backend.c | 3 +-
t/t5510-fetch.sh | 6 +-
t/t6302-for-each-ref-filter.sh | 34 ++++++++
10 files changed, 207 insertions(+), 106 deletions(-)

--
2.45.0