Re: [PATCH 00/12] show-ref: introduce mode to check for ref existence

[Patrick Steinhardt <ps@pks.im>]

[-- Attachment #1: Type: text/plain, Size: 3457 bytes --]

On Wed, Oct 25, 2023 at 04:26:35PM +0200, Han-Wen Nienhuys wrote:
> On Tue, Oct 24, 2023 at 9:17 PM Junio C Hamano <gitster@pobox.com> wrote:
> >
> > Patrick Steinhardt <ps@pks.im> writes:
> >
> > > this patch series introduces a new `--exists` mode to git-show-ref(1) to
> > > explicitly check for the existence of a reference, only.
> >
> > I agree that show-ref would be the best place for this feature (not
> > rev-parse, which is already a kitchen sink).  After all, the command
> > was designed for validating refs in 358ddb62 (Add "git show-ref"
> > builtin command, 2006-09-15).
> >
> > Thanks.  Hopefully I can take a look before I go offline.
> 
> The series description doesn't say why users would care about this.
> 
> If this is just to ease testing, I suggest adding functionality to a
> suitable test helper. Anything you add to git-show-ref is a publicly
> visible API that needs documentation and comes with a stability
> guarantee that is more expensive to maintain than test helper
> functionality.

The first patch of the original patch series where I split this out from
did exactly that, see [1]. Junio questioned though whether this should
be part of production code instead of being a test helper.

And I tend to agree with him, or otherwise I wouldn't have written this
series. It's actually a bit surprising that we do not have any way to
test for reference existence in any of our helpers in a generic way. All
current tooling that I'm aware of is lacking in some ways:

    - git-rev-parse(1) will fail to parse symbolic refs whose target
      does not exist.

    - git-symbolic-ref(1) can look up such unborn branches, but the
      caller needs to be aware that 

    - git-show-ref(1) tries to resolve symbolic references.

    - git-for-each-ref(1) is simply not an obvious way to check for ref
      existence.

    - All of these will fail to parse references with malformed names.

So the new `git show-ref --exists` mode is a trivial-to-use and generic
way to simply ask "Do you know this reference?". The lack of this option
likely shows that you can most often get away without such a tool, but I
still find it funny that there is no obvious way to perform this query
right now.

At the Contributor's Summit, we've also discussed the issue that our
plumbing layer has become less useful over the years. It is often
missing functionality that exists in user-facing commands. It also has
inherited many of the restrictions of our porcelain tools, like not
being able to look up references with bad names. So this series is a
small step into the direction of making our plumbing more useful again.

I also assume that it's only going to become more important to address
these limitations in our plumbing layer once we have something like the
reftable backend. A user or admin would have been able to fix issues
with misformatted referencen names rather easily in the reffiles backend
even without support in our plumbing layer, as it mostly was a single
"rm .git/refs/$broken_ref" away. But that's not going to be an easy
solution anymore with reftable due to the complexity of its format. So I
also see it as part of the upcoming preparatory work to make sure that
they have all the necessary tools to address such situations, at least
up to a reasonable point.

Patrick

[1]: <e947feb1c77f7e9f3c7f983bbe47137fbce42367.1697607222.git.ps@pks.im>

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]