[GSoC][RFC PATCH v3 0/3] Add refs list subcommand

[Meet Soni <meetsoni3017@gmail.com>]

Hello everyone,

This is the third version of the patch series that introduces the `git
refs list` subcommand as a modern alternative to `git for-each-ref`.

Thank you to everyone who provided valuable feedback on the patch
series.

Changes in v3:
  - Restructured the patch series from two commits into three, providing
    a cleaner separation between the feature implementation, the test
    refactoring, and the new test itself.

  - Reworked the testing approach to follow the established pattern for
    shared tests (like git-blame/annotate). The core test logic now
    resides in a shared file (`for-each-ref-tests.sh`), which is sourced
    by both the original `t6300-for-each-ref.sh` and the new
    `t1461-refs-list.sh` test drivers.

  - Adopted the suggested `$git_for_each_ref` variable convention in the
    test suite for better clarity and to demonstrate the drop-in
    compatibility.

  - Removed unwanted comment.

---

(v1 cover-letter text)

This patch series introduces `git refs list` as a modern replacement for
`git for-each-ref`, as part of an effort to consolidate ref-related
functionality under a unified `git refs` command.

Git's ref-related operations are currently handled by several distinct
commands, such as `git show-ref`, `git for-each-ref`, `git update-ref`,
`git pack-refs`, etc. This distribution has a few practical drawbacks:

- Users need to rely on multiple commands for related tasks involving
  refs.

- The commands may differ slightly in behavior and option syntax,
  leading to inconsistency.

We propose a long-term consolidation effort to bring ref-related
subcommands under the umbrella of a single command: `git refs`.

The implementation of `git refs list` is functionally identical to `git
for-each-ref`. It reuses the same internal logic (cmd_for_each_ref) to
ensure complete backward compatibility. The purpose of this patch is not
to introduce new behavior but to provide an alternate entry point under
the consolidated `git refs` namespace.

The motivation behind this change is twofold:

- Consolidation: Centralizing ref-related operations makes them easier
  to discover, use, and maintain.

- Evolution: While the initial goal is parity with existing commands,
  this consolidation allows for careful reconsideration of which
  features are essential. Over time, we can:

  - Remove legacy or obscure options that are no longer needed.
  - Add improvements that wouldn't make sense to bolt onto legacy
    commands.
  - Offering a more consistent and user-friendly surface.

To verify backward compatibility, this patch also includes a test
`t/t1461-refs-list.sh`, which runs the full `t6300-for-each-ref.sh` test
using `git refs list`. The test uses ${GIT_REFS_LIST_CMD:-for-each-ref}
to allow substitution without duplicating tests.

This patch is deliberately conservative: it introduces no behavioral
changes and leaves `for-each-ref` untouched. The goal is to lay
groundwork and demonstrate viability of ref consolidation within `git
refs`.

Going forward, I'd like to initiate a discussion on what the ideal
surface of `git refs list` should look like. Which options and features
from `for-each-ref` should be carried over? Are there any that are
obsolete or overly niche? What improvements might be worth considering
now that we have a new, consolidated interface?

Feedback on this, especially from those who rely on `for-each-ref` in
scripts or tooling would be very helpful.

Meet Soni (3):
  builtin/refs: add list subcommand
  t6300: refactor tests to be shareable
  t: add test for git refs list subcommand

 Documentation/git-for-each-ref.adoc  |   80 +-
 Documentation/git-refs.adoc          |   16 +
 Documentation/refs-list-options.adoc |   79 +
 builtin/for-each-ref.c               |   24 +-
 builtin/refs.c                       |   35 +
 t/for-each-ref-tests.sh              | 2141 ++++++++++++++++++++++++++
 t/meson.build                        |    1 +
 t/t1461-refs-list.sh                 |    8 +
 t/t6300-for-each-ref.sh              | 2140 +------------------------
 9 files changed, 2303 insertions(+), 2221 deletions(-)
 create mode 100644 Documentation/refs-list-options.adoc
 create mode 100644 t/for-each-ref-tests.sh
 create mode 100755 t/t1461-refs-list.sh

Range-diff against v2:
1:  b2d3026520 ! 1:  547b0bbf8f builtin/refs: add list subcommand
    @@ Documentation/git-refs.adoc: The following options are specific to 'git refs ver
     
      ## Documentation/refs-list-options.adoc (new) ##
     @@
    -+// Shared options for for-each-ref and refs list
     +<pattern>...::
     +	If one or more patterns are given, only refs are shown that
     +	match against at least one pattern, either using fnmatch(3) or
2:  2d6534841f < -:  ---------- t: add test for git refs list subcommand
-:  ---------- > 2:  5d5057ff98 t6300: refactor tests to be shareable
-:  ---------- > 3:  b9cb9cdf48 t: add test for git refs list subcommand
-- 
2.34.1