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

Hi,

this is the third version of my patch series that aims to clarify the pseudo-ref terminology.

Changes compared to v2:

    - Various typo fixes.

    - Added a note in the first commit that we're about to clearly
      define rules around "root refs" in a subsequent commit. While this
      patch series will make root refs act like "just a normal ref", we
      will still have strict limits around the naming policy for them.

Thanks!

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 |  72 ++++++++---------
 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, 205 insertions(+), 105 deletions(-)

Range-diff against v2:
 1:  2489bb5585 !  1:  e651bae690 Documentation/glossary: redefine pseudorefs as special refs
    @@ Commit message
     
         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"
    +    ref. And we really only have two of these nowadays, namely "MERGE_HEAD"
         and "FETCH_HEAD". Those files are never written via the ref backends,
         but are instead written by git-fetch(1), git-pull(1) and git-merge(1).
    -    They contain additional metadata that hihlights where a ref has been
    +    They contain additional metadata that highlights where a ref has been
         fetched from or the list of commits that have been merged.
     
         This original intent in fact matches the definition of special refs that
    @@ Commit message
         definition, we can drop the "special refs" term again. It's not exposed
         to our users and thus they wouldn't ever encounter that term anyway.
     
    +    Refs that live in the root of the ref hierarchy but which are not
    +    pseudorefs will be further defined in a subsequent commit.
    +
         Signed-off-by: Patrick Steinhardt <ps@pks.im>
     
      ## Documentation/glossary-content.txt ##
     @@ Documentation/glossary-content.txt: exclude;;
    - 	that start with `refs/bisect/`, but might later include other
      	unusual refs.
      
    --[[def_pseudoref]]pseudoref::
    + [[def_pseudoref]]pseudoref::
     -	Pseudorefs are a class of files under `$GIT_DIR` which behave
     -	like refs for the purposes of rev-parse, but which are treated
     -	specially by git.  Pseudorefs both have names that are all-caps,
    @@ Documentation/glossary-content.txt: exclude;;
     -	they are updated by directly writing to the files.  However,
     -	they can be read as if they were refs, so `git rev-parse
     -	MERGE_HEAD` will work.
    -+[[def_pseudoref]]pseudoref ref::
     +	A ref that has different semantics than normal refs. These refs can be
     +	accessed via normal Git commands but may not behave the same as a
     +	normal ref in some cases.
 2:  1f2f8cf3f2 !  2:  66ac046132 Documentation/glossary: clarify limitations of pseudorefs
    @@ Commit message
           - They can be read via git-rev-parse(1) and similar tools.
     
           - They are not surfaced when iterating through refs, like when using
    -        git-for-each-ref(1). They are no ref, so iterating through refs
    +        git-for-each-ref(1). They are not refs, so iterating through refs
             should not surface them.
     
           - They cannot be written via git-update-ref(1) and related commands.
    @@ Commit message
      ## Documentation/glossary-content.txt ##
     @@ Documentation/glossary-content.txt: exclude;;
      
    - [[def_pseudoref]]pseudoref ref::
    + [[def_pseudoref]]pseudoref::
      	A ref that has different semantics than normal refs. These refs can be
     -	accessed via normal Git commands but may not behave the same as a
     -	normal ref in some cases.
 3:  9659d7da3f !  3:  243d616101 Documentation/glossary: define root refs as refs
    @@ Documentation/glossary-content.txt: The following pseudorefs are known to Git:
     -Different subhierarchies are used for different purposes (e.g. the
     -`refs/heads/` hierarchy is used to represent local branches).
     +Ref names must either start with `refs/` or be located in the root of
    -+the hierarchy. In that case, their name must conform to the following
    -+rules:
    ++the hierarchy. For the latter, their name must follow these rules:
      +
     -There are a few special-purpose refs that do not begin with `refs/`.
     -The most notable example is `HEAD`.
 4:  3d7ea70417 =  4:  0a116f9d11 refs: rename `is_pseudoref()` to `is_root_ref()`
 5:  e6b6db972d !  5:  484a0856bc refs: refname `is_special_ref()` to `is_pseudo_ref()`
    @@ Commit message
         defined terminology in our gitglossary(7). Note that in the preceding
         commit we have just renamed `is_pseudoref()` to `is_root_ref()`, where
         there may be confusion for in-flight patch series that add new calls to
    -    `is_pseudoref()`. In order to intentionall break such patch series we
    +    `is_pseudoref()`. In order to intentionally break such patch series we
         have thus picked `is_pseudo_ref()` instead of `is_pseudoref()` as the
         new name.
     
 6:  44f72a7baf =  6:  c196fe3c45 refs: classify HEAD as a root ref
 7:  e90b2f8aa9 !  7:  92a71222e1 refs: root refs can be symbolic refs
    @@ Commit message
     
         Last but not least, the current behaviour can actually lead to a
         segfault when calling `is_root_ref()` with a reference that either does
    -    not exist or that is a symbolic ref because we never intialized `oid`.
    +    not exist or that is a symbolic ref because we never initialized `oid`.
     
         Let's loosen the restrictions in accordance to the new definition of
         root refs, which are simply plain refs that may as well be a symbolic
 8:  bc82d7ae65 =  8:  8bd52e5363 refs: pseudorefs are no refs
 9:  95d7547b2e =  9:  cd6d745a01 ref-filter: properly distinuish pseudo and root refs
10:  b2029612dd = 10:  6956fccced refs: refuse to write pseudorefs