Re: [GSoC][PATCH] builtin/refs: add 'get' subcommand

From: Patrick Steinhardt <ps@pks.im>
Date: Sep 25, 2025, 06:25 UTC
Message-ID: <aNTgRGeaPajVz1dv@pks.im>
In-Reply-To: <xmqq7bxnn5cj.fsf@gitster.g>

On Wed, Sep 24, 2025 at 10:11:08AM -0700, Junio C Hamano wrote:

Show 14 quoted lines

> 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...

Show 20 quoted lines

> > 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.

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