Subject: Re: [GSoC][RFC PATCH 0/2] Add refs list subcommand

From: Junio C Hamano <[email-masked]>
Date: Mon, 30 Jun 2025 13:10:36 -0700

Meet Soni <[email-masked]> writes:

> To clarify, I don't have specific options or improvements in mind right now.
> The idea behind mentioning them was to acknowledge that having a consolidated
> interface like git refs might open the door to such discussions.

One complaint we heard a lot about Git in the past (I do not know if
people got used to and learned to live with, or they are still
complaining about the same these days) was that there were always
multiple ways to do related things slightly differently.

The machinery of for-each-ref is shared by branch and tag to give
them feature-parity.  Adding yet another command that behaves
slightly differently, with the intention to make it diverge even
more in the future, feels going backwards.

> The primary motivation here is to make ref-related commands discoverable at a
> single entry point - git refs, rather than scattered across several top-level
> commands. The aim is to improve disoverability and set the stage for
> potential future
> cleanup or enhancements, should the community find value in doing so.

We need to be a bit careful.  There was a case that went in a
totally opposite direction.  Even though a single command was there
in the beginning that can be used to pick a specific thing out of
the histories stored in a repository to externalize it in the file
system to be worked on, it was later split into two commands as
folks thought it would make it more discoverable.

Even though branches, tags, and symbolic refs like HEAD are all
refs, from the point of view of end-users, they are different things
built on top of the same underlying mechanism.  The fact that they
share the underlying mechanism does not necessarily mean that a
single same command is easier to discover and work on them to the
users.

It may not hurt too much to have "enumerate all refs, and for each
ref, allowing to limit them or to sort them with some criteria, and
show them in a customizable format" as "git refs list", but we do
need to keep the feature parity with "git for-each-ref".  Adding
unnecessary subtle differences would only confuse users.