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@xxxxxx>
## 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
Attachment:
signature.asc
Description: PGP signature
