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 ## 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 -- 2.45.0