From: Patrick Steinhardt <ps@pks.im>
To: git@vger.kernel.org, Jeff King <peff@peff.net>,
Karthik Nayak <karthik.188@gmail.com>
Subject: Re: [PATCH 2/3] refs: do not label special refs as pseudo refs
Date: Tue, 30 Apr 2024 09:29:59 +0200 [thread overview]
Message-ID: <ZjCd97dqiHfkm1UG@tanuki> (raw)
In-Reply-To: <5322n7eqkov3fqw2zw2seiqyqcmmrlo35camq76n546dkgycru@njuj32gmbogh>
[-- Attachment #1: Type: text/plain, Size: 5114 bytes --]
On Mon, Apr 29, 2024 at 05:52:41PM -0500, Justin Tobler wrote:
> On 24/04/29 03:41PM, Patrick Steinhardt wrote:
> > diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt
> > index d71b199955..4275918fa0 100644
> > --- a/Documentation/glossary-content.txt
> > +++ b/Documentation/glossary-content.txt
> > @@ -497,20 +497,28 @@ exclude;;
> > unusual refs.
> >
> > [[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,
> > - and always start with a line consisting of a
> > - <<def_SHA1,SHA-1>> followed by whitespace. So, HEAD is not a
> > - pseudoref, because it is sometimes a symbolic ref. They might
>
> We remove the example here about HEAD not being a pseudoref. This
> example seems helpful to indicate that a pseudoref cannot be a symbolic
> ref. Is this no longer the case and the change intended?
I just don't see why we would want to have this restriction. Honestly,
the more I think about this whole topic the more I want to go into the
direction I've hinted at in the cover letter: drop "special refs" and
define pseudo refs as either FETCH_HEAD or MERGE_HEAD. Everything else
is just a normal ref, even though some of those may live in the root
directory if they conform to a set of strict rules:
- All upppercase characters plus underscores.
- Must end with "_HEAD", except a list of known irregular root refs.
I feel like the world would be better like this.
> > - optionally contain some additional data. `MERGE_HEAD` and
> > - `CHERRY_PICK_HEAD` are examples. Unlike
> > - <<def_per_worktree_ref,per-worktree refs>>, these files cannot
> > - be symbolic refs, and never have reflogs. They also cannot be
> > - updated through the normal ref update machinery. Instead,
> > - 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.
> > + Pseudorefs are references that live in the root of the reference
> > + hierarchy, outside of the usual "refs/" hierarchy. Pseudorefs have an
> > + all-uppercase name and must end with a "_HEAD" suffix, for example
> > + "`BISECT_HEAD`". Other than that, pseudorefs behave the exact same as
> > + any other reference and can be both read and written via regular Git
> > + tooling.
>
> Pseudorefs behaving the same and using the same tooling seems to
> contridict the previous documentation. I assume the previous information
> was out-of-date, but it might be nice to explain this in the message.
Yes, and I actually want to change this. We never enforced restrictions
for pseudorefs anyway, they can be symrefs just fine. And neither would
I see any reason why that should be the case in the first place.
> > ++
> > +<<def_special_ref>,Special refs>> are not pseudorefs.
> > ++
> > +Due to historic reasons, Git has several irregular pseudo refs that do not
> > +follow above rules. The following list of irregular pseudo refs is exhaustive
>
> We seem to be inconsistent between using "pseudoref" and "pseudo ref".
> Not sure it we want to be consistent here.
Makes sense.
Patrick
> -Justin
>
> > +and shall not be extended in the future:
> > +
> > + - "`AUTO_MERGE`"
> > +
> > + - "`BISECT_EXPECTED_REV`"
> > +
> > + - "`NOTES_MERGE_PARTIAL`"
> > +
> > + - "`NOTES_MERGE_REF`"
> > +
> > + - "`MERGE_AUTOSTASH`"
> >
> > [[def_pull]]pull::
> > Pulling a <<def_branch,branch>> means to <<def_fetch,fetch>> it and
> > diff --git a/refs.c b/refs.c
> > index c64f66bff9..567c6fc6ff 100644
> > --- a/refs.c
> > +++ b/refs.c
> > @@ -905,6 +905,8 @@ int is_pseudoref(struct ref_store *refs, const char *refname)
> >
> > if (!is_pseudoref_syntax(refname))
> > return 0;
> > + if (is_special_ref(refname))
> > + return 0;
> >
> > if (ends_with(refname, "_HEAD")) {
> > refs_resolve_ref_unsafe(refs, refname,
> > diff --git a/t/t6302-for-each-ref-filter.sh b/t/t6302-for-each-ref-filter.sh
> > index 948f1bb5f4..8c92fbde79 100755
> > --- a/t/t6302-for-each-ref-filter.sh
> > +++ b/t/t6302-for-each-ref-filter.sh
> > @@ -52,6 +52,23 @@ test_expect_success '--include-root-refs pattern prints pseudorefs' '
> > test_cmp expect actual
> > '
> >
> > +test_expect_success '--include-root-refs pattern does not print special refs' '
> > + test_when_finished "rm -rf repo" &&
> > + git init repo &&
> > + (
> > + cd repo &&
> > + test_commit initial &&
> > + git rev-parse HEAD >.git/MERGE_HEAD &&
> > + git for-each-ref --format="%(refname)" --include-root-refs >actual &&
> > + cat >expect <<-EOF &&
> > + HEAD
> > + $(git symbolic-ref HEAD)
> > + refs/tags/initial
> > + EOF
> > + test_cmp expect actual
> > + )
> > +'
> > +
> > test_expect_success '--include-root-refs with other patterns' '
> > cat >expect <<-\EOF &&
> > HEAD
> > --
> > 2.45.0-rc1
> >
>
>
[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]
next prev parent reply other threads:[~2024-04-30 7:32 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 [this message]
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 ` [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=ZjCd97dqiHfkm1UG@tanuki \
--to=ps@pks.im \
--cc=git@vger.kernel.org \
--cc=karthik.188@gmail.com \
--cc=peff@peff.net \
/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).