From: D. Ben Knoble <ben.knoble@gmail.com>
Date: Thu, 25 Sep 2025 18:08:11 GMT
Subject: Re: [GSoC][PATCH] builtin/refs: add 'get' subcommand
Message-ID: <CALnO6CD0fCF15Vdh7_AtuWiKeXUFbU_kqV=+wAMkmABzchV=Tw@mail.gmail.com>
In-Reply-To: <aNTgRGeaPajVz1dv@pks.im>

On Thu, Sep 25, 2025 at 2:25 AM Patrick Steinhardt <ps@pks.im> wrote:
>
> On Wed, Sep 24, 2025 at 10:11:08AM -0700, Junio C Hamano wrote:
> > Ben Knoble <ben.knoble@gmail.com> writes:
> >
> > >>> Perhaps "show-ref --verify --no-deref" or something that does not
> > >>> dereference but works directly on a symbolic ref?
> > >>
> > >> For now: yes, it's more difficult to discover for sure. But users will
> > >> adjust over time as they get more familiar with git-refs(1), and from
> > >> thereon I think it will become significantly easier to discover that
> > >> subcommand.
> >
> > But unfortunately, that is a tautology, isn't it?  With the same
> > effort to advertise git-refs to make it more familiar to the
> > "users", you can make "show-ref" familiar to the same "users", and
> > problem solved, without a need to do anything to "git-refs"?
>
> I don't quite think so. The problem is that we have so many different
> tools that relate to refs, and you have to remember all of them:
>
>   - `git show-refs --verify` to read a single reference, unless it's a
>     symbolic reference.
>
>   - `git symbolic-ref` to read symbolic refs.
>
>   - `git show-refs --exists` to check a reference for existence.
>
>   - `git show-ref` and `git for-each-ref` to list references.
>
>   - `git pack-refs` to optimize references.
>
>   - `git update-refs` to update references`
>
> I'd claim that this is quite hard to remember. So...

Agreed! To be clear: me asking questions should be taken as support
for this exercise :)

> > > I think this goes to perhaps some of my unasked questions: who is
> > > the target audience? My experience suggest that most
> > > mostly-porcelain users don’t acquire familiarity with scripting
> > > commands, so it sounds like we’re talking about script-writers
> > > here (and in the commit message).
> > >
> > > But how do we encourage script writers to discover these things? 🤔 Hm.
> >
> > Great question.  I understand what the patch author is trying to
> > achieve (i.e. "consolidate ref-related functionality into git-refs",
> > which is the title of GSoC project [*]), but what are we, as Git
> > project, trying to achive by "consolidating"?  I often cannot shake
> > the feeling that it may a make-work job without a clear answer to
> > that question.  Or perhps xkcd.com/927/?
> >
> > Perhaps the hope is to have a single kitchen sink "git refs" command
> > that does anything related to "refs", so that they only need to
> > learn this single command (and unlearn all the previous experiences
> > they gained) and after that, they do not have to "discover" more
> > things?
>
> ... yes, this is exactly the goal of this exercise. You basically only
> need to know about the entrypoint git-refs(1). Once you know about it,
> you don't have to discover all the other commands, as it is now way
> easier to discover what ref-related functionality you have available.
> You can easily use tab completion (well, once it's wired up), type `git
> refs -h` to learn about evertyhing refs, and we now have a single
> manpage that will tell you everything about ref-related use commands.

Ah, but here's perhaps my question: tab-completion suggests primarily
porcelain users over plumbing users, to me ;)

I admit I blur the line quite a bit myself, being unafraid to string
together plumbing commands at a live shell (or make abominations like
git-greb [1]).

At any rate, the target audience need not be precise now. I hope my
confusion is clear, though :)

[1]: https://benknoble.github.io/blog/2025/09/17/blame/

> You could partially address that problem by providing a gitrefs(5)
> manpage that gives an overview. And maybe that's still something one
> could do, also to paint a bit of a broader picture. But documentation is
> only part of the solution -- with git-refs(1) we get some "natural"
> discoverability.
>
> That's also where the "git refs get" proposal comes from. Sure, you can
> use `git show-refs --verify`, potentially with a `--no-dereference` flag
> if you want to read normal refs. But I would claim that this is almost
> impossible to discover without searching through our manpages.
>
> Patrick

This all makes sense to me.

-- 
D. Ben Knoble