From: Patrick Steinhardt <ps@pks.im>
To: git@vger.kernel.org
Cc: Jeff King <peff@peff.net>, Karthik Nayak <karthik.188@gmail.com>,
Phillip Wood <phillip.wood123@gmail.com>,
Junio C Hamano <gitster@pobox.com>,
Justin Tobler <jltobler@gmail.com>,
Kristoffer Haugsbakk <code@khaugsbakk.name>
Subject: [PATCH v3 00/10] Clarify pseudo-ref terminology
Date: Thu, 2 May 2024 10:17:08 +0200 [thread overview]
Message-ID: <cover.1714637671.git.ps@pks.im> (raw)
In-Reply-To: <cover.1714398019.git.ps@pks.im>
[-- Attachment #1: Type: text/plain, Size: 7096 bytes --]
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
--
2.45.0
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2024-05-02 8:17 UTC|newest]
Thread overview: 93+ messages / expand[flat|nested] mbox.gz Atom feed top
2024-04-29 13:41 [PATCH 0/3] Clarify pseudo-ref terminology Patrick Steinhardt
2024-04-29 13:41 ` [PATCH 1/3] refs: move `is_special_ref()` Patrick Steinhardt
2024-04-29 13:41 ` [PATCH 2/3] refs: do not label special refs as pseudo refs Patrick Steinhardt
2024-04-29 15:12 ` Phillip Wood
2024-04-30 7:30 ` Patrick Steinhardt
2024-04-30 9:59 ` Phillip Wood
2024-04-30 12:11 ` Patrick Steinhardt
2024-04-30 10:23 ` Jeff King
2024-04-30 12:07 ` Karthik Nayak
2024-04-30 12:33 ` Patrick Steinhardt
2024-04-30 12:16 ` Patrick Steinhardt
2024-04-29 16:24 ` Junio C Hamano
2024-04-29 22:52 ` Justin Tobler
2024-04-30 7:29 ` Patrick Steinhardt
2024-05-09 17:29 ` Jean-Noël AVILA
2024-05-10 8:33 ` Patrick Steinhardt
2024-04-29 13:41 ` [PATCH 3/3] refs: fix segfault in `is_pseudoref()` when ref cannot be resolved Patrick Steinhardt
2024-04-29 15:25 ` Phillip Wood
2024-04-29 18:57 ` Karthik Nayak
2024-04-29 19:47 ` Phillip Wood
2024-04-29 20:44 ` Karthik Nayak
2024-04-30 7:30 ` Patrick Steinhardt
2024-04-30 12:26 ` [PATCH v2 00/10] Clarify pseudo-ref terminology Patrick Steinhardt
2024-04-30 12:26 ` [PATCH v2 01/10] Documentation/glossary: redefine pseudorefs as special refs Patrick Steinhardt
2024-04-30 12:49 ` Karthik Nayak
2024-04-30 17:17 ` Justin Tobler
2024-04-30 20:12 ` Junio C Hamano
2024-05-02 8:07 ` Patrick Steinhardt
2024-04-30 12:26 ` [PATCH v2 02/10] Documentation/glossary: clarify limitations of pseudorefs Patrick Steinhardt
2024-04-30 13:35 ` Kristoffer Haugsbakk
2024-04-30 12:26 ` [PATCH v2 03/10] Documentation/glossary: define root refs as refs Patrick Steinhardt
2024-04-30 12:56 ` Karthik Nayak
2024-04-30 12:26 ` [PATCH v2 04/10] refs: rename `is_pseudoref()` to `is_root_ref()` Patrick Steinhardt
2024-04-30 20:20 ` Junio C Hamano
2024-04-30 12:26 ` [PATCH v2 05/10] refs: refname `is_special_ref()` to `is_pseudo_ref()` Patrick Steinhardt
2024-04-30 12:58 ` Karthik Nayak
2024-04-30 12:26 ` [PATCH v2 06/10] refs: classify HEAD as a root ref Patrick Steinhardt
2024-04-30 12:26 ` [PATCH v2 07/10] refs: root refs can be symbolic refs Patrick Steinhardt
2024-04-30 17:09 ` Justin Tobler
2024-05-02 8:07 ` Patrick Steinhardt
2024-05-03 20:49 ` Justin Tobler
2024-05-07 10:32 ` Patrick Steinhardt
2024-04-30 12:26 ` [PATCH v2 08/10] refs: pseudorefs are no refs Patrick Steinhardt
2024-04-30 12:27 ` [PATCH v2 09/10] ref-filter: properly distinuish pseudo and root refs Patrick Steinhardt
2024-04-30 13:11 ` Karthik Nayak
2024-05-02 8:08 ` Patrick Steinhardt
2024-05-02 10:03 ` Karthik Nayak
2024-04-30 12:27 ` [PATCH v2 10/10] refs: refuse to write pseudorefs Patrick Steinhardt
2024-05-02 8:17 ` Patrick Steinhardt [this message]
2024-05-02 8:17 ` [PATCH v3 01/10] Documentation/glossary: redefine pseudorefs as special refs Patrick Steinhardt
2024-05-02 8:17 ` [PATCH v3 02/10] Documentation/glossary: clarify limitations of pseudorefs Patrick Steinhardt
2024-05-02 8:17 ` [PATCH v3 03/10] Documentation/glossary: define root refs as refs Patrick Steinhardt
2024-05-02 8:17 ` [PATCH v3 04/10] refs: rename `is_pseudoref()` to `is_root_ref()` Patrick Steinhardt
2024-05-02 8:17 ` [PATCH v3 05/10] refs: refname `is_special_ref()` to `is_pseudo_ref()` Patrick Steinhardt
2024-05-02 8:17 ` [PATCH v3 06/10] refs: classify HEAD as a root ref Patrick Steinhardt
2024-05-02 8:17 ` [PATCH v3 07/10] refs: root refs can be symbolic refs Patrick Steinhardt
2024-05-03 18:13 ` Jeff King
2024-05-15 4:16 ` Patrick Steinhardt
2024-05-15 4:39 ` Patrick Steinhardt
2024-05-15 6:22 ` Jeff King
2024-05-15 6:35 ` Patrick Steinhardt
2024-05-15 6:49 ` Jeff King
2024-05-15 6:59 ` Patrick Steinhardt
2024-05-15 6:20 ` Jeff King
2024-05-02 8:17 ` [PATCH v3 08/10] refs: pseudorefs are no refs Patrick Steinhardt
2024-05-02 8:17 ` [PATCH v3 09/10] ref-filter: properly distinuish pseudo and root refs Patrick Steinhardt
2024-05-02 8:17 ` [PATCH v3 10/10] refs: refuse to write pseudorefs Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 00/10] Clarify pseudo-ref terminology Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 01/10] Documentation/glossary: redefine pseudorefs as special refs Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 02/10] Documentation/glossary: clarify limitations of pseudorefs Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 03/10] Documentation/glossary: define root refs as refs Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 04/10] refs: rename `is_pseudoref()` to `is_root_ref()` Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 05/10] refs: refname `is_special_ref()` to `is_pseudo_ref()` Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 06/10] refs: root refs can be symbolic refs Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 07/10] refs: classify HEAD as a root ref Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 08/10] refs: pseudorefs are no refs Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 09/10] ref-filter: properly distinuish pseudo and root refs Patrick Steinhardt
2024-05-10 8:48 ` [PATCH v4 10/10] refs: refuse to write pseudorefs Patrick Steinhardt
2024-05-10 18:59 ` [PATCH v4 00/10] Clarify pseudo-ref terminology Junio C Hamano
2024-05-15 6:50 ` [PATCH v5 " Patrick Steinhardt
2024-05-15 6:50 ` [PATCH v5 01/10] Documentation/glossary: redefine pseudorefs as special refs Patrick Steinhardt
2024-05-15 6:50 ` [PATCH v5 02/10] Documentation/glossary: clarify limitations of pseudorefs Patrick Steinhardt
2024-05-15 6:50 ` [PATCH v5 03/10] Documentation/glossary: define root refs as refs Patrick Steinhardt
2024-05-15 6:50 ` [PATCH v5 04/10] refs: rename `is_pseudoref()` to `is_root_ref()` Patrick Steinhardt
2024-05-15 6:50 ` [PATCH v5 05/10] refs: rename `is_special_ref()` to `is_pseudo_ref()` Patrick Steinhardt
2024-05-15 6:50 ` [PATCH v5 06/10] refs: do not check ref existence in `is_root_ref()` Patrick Steinhardt
2024-05-15 20:38 ` Justin Tobler
2024-05-16 4:13 ` Patrick Steinhardt
2024-05-15 6:50 ` [PATCH v5 07/10] refs: classify HEAD as a root ref Patrick Steinhardt
2024-05-15 20:44 ` Justin Tobler
2024-05-15 6:51 ` [PATCH v5 08/10] refs: pseudorefs are no refs Patrick Steinhardt
2024-05-15 6:51 ` [PATCH v5 09/10] ref-filter: properly distinuish pseudo and root refs Patrick Steinhardt
2024-05-15 6:51 ` [PATCH v5 10/10] refs: refuse to write pseudorefs Patrick Steinhardt
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
List information: http://vger.kernel.org/majordomo-info.html
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=cover.1714637671.git.ps@pks.im \
--to=ps@pks.im \
--cc=code@khaugsbakk.name \
--cc=git@vger.kernel.org \
--cc=gitster@pobox.com \
--cc=jltobler@gmail.com \
--cc=karthik.188@gmail.com \
--cc=peff@peff.net \
--cc=phillip.wood123@gmail.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).