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>,
"Jean-Noël AVILA" <avila.jn@gmail.com>
Subject: [PATCH v4 00/10] Clarify pseudo-ref terminology
Date: Fri, 10 May 2024 10:48:01 +0200 [thread overview]
Message-ID: <cover.1715330206.git.ps@pks.im> (raw)
In-Reply-To: <cover.1714398019.git.ps@pks.im>
[-- Attachment #1: Type: text/plain, Size: 9595 bytes --]
Hi,
thi sis the fourth version of my patch series that aims to clarify the
pseudo-ref terminology. Changes compared to v3:
- Render refs in "Documentation/glossary-context.txt" more
consistently with backticks, only.
- Reorder patches 6 and 7 such that we first correct `is_root_ref()`,
and then adapt `is_headref()`.
- Furthermore, I have inlined `is_headref()` into `is_root_ref()`
completely now as it didn't have any users anymore.
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: root refs can be symbolic refs
refs: classify HEAD as a root ref
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 | 108 ++++++++++++++---------------
refs.h | 48 ++++++++++++-
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, 185 insertions(+), 111 deletions(-)
Range-diff against v3:
1: e651bae690 ! 1: b1fc4c1ac7 Documentation/glossary: redefine pseudorefs as special refs
@@ Documentation/glossary-content.txt: exclude;;
++
+The following pseudorefs are known to Git:
+
-+ - "`FETCH_HEAD`" is written by linkgit:git-fetch[1] or linkgit:git-pull[1]. It
++ - `FETCH_HEAD` is written by linkgit:git-fetch[1] or linkgit:git-pull[1]. It
+ may refer to multiple object IDs. Each object ID is annotated with metadata
+ indicating where it was fetched from and its fetch status.
+
-+ - "`MERGE_HEAD`" is written by linkgit:git-merge[1] when resolving merge
++ - `MERGE_HEAD` is written by linkgit:git-merge[1] when resolving merge
+ conflicts. It contains all commit IDs which are being merged.
[[def_pull]]pull::
2: 66ac046132 = 2: dce3a0fa7e Documentation/glossary: clarify limitations of pseudorefs
3: 243d616101 ! 3: 79249962f5 Documentation/glossary: define root refs as refs
@@ Documentation/glossary-content.txt: The following pseudorefs are known to Git:
+match these rules. The following list is exhaustive and shall not be
+extended in the future:
++
-+ - AUTO_MERGE
++ - `AUTO_MERGE`
+
-+ - BISECT_EXPECTED_REV
++ - `BISECT_EXPECTED_REV`
+
-+ - NOTES_MERGE_PARTIAL
++ - `NOTES_MERGE_PARTIAL`
+
-+ - NOTES_MERGE_REF
++ - `NOTES_MERGE_REF`
+
-+ - MERGE_AUTOSTASH
++ - `MERGE_AUTOSTASH`
++
+Different subhierarchies are used for different purposes. For example,
+the `refs/heads/` hierarchy is used to represent local branches whereas
4: 0a116f9d11 = 4: ee2b090f75 refs: rename `is_pseudoref()` to `is_root_ref()`
5: 484a0856bc = 5: 2c09bc7690 refs: refname `is_special_ref()` to `is_pseudo_ref()`
7: 92a71222e1 ! 6: 5e402811a6 refs: root refs can be symbolic refs
@@ Commit message
does not seem reasonable at all and I very much doubt that it results in
anything sane.
- Furthermore, the behaviour is different to `is_headref()`, which only
- checks for the ref to exist. While that is in line with our glossary,
- this inconsistency only adds to the confusion.
-
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 initialized `oid`.
@@ refs.c: int is_root_ref(struct ref_store *refs, const char *refname)
size_t i;
if (!is_root_ref_syntax(refname))
-@@ refs.c: int is_root_ref(struct ref_store *refs, const char *refname)
- if (is_headref(refs, refname))
- return 1;
+ return 0;
+ /*
+ * Note that we cannot use `refs_ref_exists()` here because that also
@@ refs.c: int is_root_ref(struct ref_store *refs, const char *refname)
}
int is_headref(struct ref_store *refs, const char *refname)
- {
-- if (!strcmp(refname, "HEAD"))
-- return refs_ref_exists(refs, refname);
-+ struct strbuf referent = STRBUF_INIT;
-+ struct object_id oid = { 0 };
-+ int failure_errno, ret = 0;
-+ unsigned int flags;
-
-- return 0;
-+ /*
-+ * Note that we cannot use `refs_ref_exists()` here because that also
-+ * checks whether its target ref exists in case refname is a symbolic
-+ * ref.
-+ */
-+ if (!strcmp(refname, "HEAD")) {
-+ ret = !refs_read_raw_ref(refs, refname, &oid, &referent,
-+ &flags, &failure_errno);
-+ }
-+
-+ strbuf_release(&referent);
-+ return ret;
- }
+
+ ## refs.h ##
+@@ refs.h: extern struct ref_namespace_info ref_namespace[NAMESPACE__COUNT];
+ void update_ref_namespace(enum ref_namespace namespace, char *ref);
- static int is_current_worktree_ref(const char *ref) {
+ /*
+- * Check whether the reference is an existing root reference.
++ * Check whether the reference is an existing root reference. A root reference
++ * that is a dangling symbolic ref is considered to exist.
+ *
+ * A root ref is a reference that lives in the root of the reference hierarchy.
+ * These references must conform to special syntax:
## t/t6302-for-each-ref-filter.sh ##
@@ t/t6302-for-each-ref-filter.sh: test_expect_success '--include-root-refs with other patterns' '
6: c196fe3c45 ! 7: b32c56afcb refs: classify HEAD as a root ref
@@ Commit message
- The "files" and "reftable" backends explicitly called both
`is_root_ref()` and `is_headref()`.
- This change should thus essentially be a no-op.
+ This also aligns behaviour or `is_root_ref()` and `is_headref()` such
+ that we also return a trueish value when the ref is a dangling symbolic
+ ref. As there are no callers of `is_headref()` left afer the refactoring
+ we absorb it completely into `is_root_ref()`.
Signed-off-by: Patrick Steinhardt <ps@pks.im>
## refs.c ##
+@@ refs.c: static int is_root_ref_syntax(const char *refname)
+ int is_root_ref(struct ref_store *refs, const char *refname)
+ {
+ static const char *const irregular_root_refs[] = {
++ "HEAD",
+ "AUTO_MERGE",
+ "BISECT_EXPECTED_REV",
+ "NOTES_MERGE_PARTIAL",
@@ refs.c: int is_root_ref(struct ref_store *refs, const char *refname)
+ return ret;
+ }
- if (!is_root_ref_syntax(refname))
- return 0;
-+ if (is_headref(refs, refname))
-+ return 1;
-
- if (ends_with(refname, "_HEAD")) {
- refs_resolve_ref_unsafe(refs, refname,
+-int is_headref(struct ref_store *refs, const char *refname)
+-{
+- if (!strcmp(refname, "HEAD"))
+- return refs_ref_exists(refs, refname);
+-
+- return 0;
+-}
+-
+ static int is_current_worktree_ref(const char *ref) {
+ return is_root_ref_syntax(ref) || is_per_worktree_ref(ref);
+ }
## refs.h ##
@@ refs.h: void update_ref_namespace(enum ref_namespace namespace, char *ref);
@@ refs.h: void update_ref_namespace(enum ref_namespace namespace, char *ref);
*/
int is_root_ref(struct ref_store *refs, const char *refname);
-+/*
-+ * Check whether the reference is "HEAD" and whether it exists.
-+ */
- int is_headref(struct ref_store *refs, const char *refname);
-
+-int is_headref(struct ref_store *refs, const char *refname);
+-
#endif /* REFS_H */
## refs/files-backend.c ##
8: 8bd52e5363 ! 8: 19af8c754c refs: pseudorefs are no refs
@@ refs.c: int is_root_ref(struct ref_store *refs, const char *refname)
+ if (!is_root_ref_syntax(refname) ||
+ is_pseudo_ref(refname))
return 0;
- if (is_headref(refs, refname))
- return 1;
+
+ /*
@@ refs.c: static int refs_read_special_head(struct ref_store *ref_store,
return result;
}
9: cd6d745a01 ! 9: 86f7f2d2d8 ref-filter: properly distinuish pseudo and root refs
@@ refs.c: int is_per_worktree_ref(const char *refname)
"MERGE_HEAD",
## refs.h ##
-@@ refs.h: int is_root_ref(struct ref_store *refs, const char *refname);
+@@ refs.h: void update_ref_namespace(enum ref_namespace namespace, char *ref);
*/
- int is_headref(struct ref_store *refs, const char *refname);
+ int is_root_ref(struct ref_store *refs, const char *refname);
+/*
+ * Pseudorefs are refs that have different semantics compared to
10: 6956fccced = 10: 640d3b169f refs: refuse to write pseudorefs
base-commit: 0f3415f1f8478b05e64db11eb8aaa2915e48fef6
--
2.45.0
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2024-05-10 8:48 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 ` [PATCH v3 00/10] Clarify pseudo-ref terminology Patrick Steinhardt
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 ` Patrick Steinhardt [this message]
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.1715330206.git.ps@pks.im \
--to=ps@pks.im \
--cc=avila.jn@gmail.com \
--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).