[GSoC][RFC PATCH v5 0/6] Add refs list subcommand

Hello Everyone,

This is the fifth version of the patch series that introduces the git refs list subcommand.

changes in v5:
  - moved changes that fixed the test into a separate commit.

--- (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 (6):
  doc: factor out common option
  builtin/for-each-ref: align usage string with the man page
  builtin/for-each-ref: factor out core logic into a helper
  builtin/refs: add list subcommand
  t6300: refactor tests to be shareable
  t: add test for git refs list subcommand

 Documentation/for-each-ref-options.adoc |   79 +
 Documentation/git-for-each-ref.adoc     |   80 +-
 Documentation/git-refs.adoc             |   16 +
 builtin/for-each-ref.c                  |   35 +-
 builtin/refs.c                          |   14 +
 for-each-ref.h                          |   26 +
 t/for-each-ref-tests.sh                 | 2141 +++++++++++++++++++++++
 t/meson.build                           |    1 +
 t/t0450/adoc-help-mismatches            |    1 -
 t/t1461-refs-list.sh                    |    8 +
 t/t6300-for-each-ref.sh                 | 2140 +---------------------
 11 files changed, 2307 insertions(+), 2234 deletions(-)
 create mode 100644 Documentation/for-each-ref-options.adoc
 create mode 100644 for-each-ref.h
 create mode 100644 t/for-each-ref-tests.sh
 create mode 100755 t/t1461-refs-list.sh

Range-diff against v4:
1:  d2fa47a2b9 = 1:  d2fa47a2b9 doc: factor out common option
-:  ---------- > 2:  48a006dca9 builtin/for-each-ref: align usage string with the man page
2:  5084db4d14 ! 3:  b7788d477a builtin/for-each-ref: factor out core logic into a helper
    @@ Commit message
     
      ## builtin/for-each-ref.c ##
     @@
    - #include "ref-filter.h"
    + #include "builtin.h"
    + #include "commit.h"
    + #include "config.h"
    ++#include "for-each-ref.h"
    + #include "gettext.h"
    + #include "object.h"
    + #include "parse-options.h"
    +@@
      #include "strbuf.h"
      #include "strvec.h"
    -+#include "for-each-ref.h"
      
    +-#define COMMON_USAGE_FOR_EACH_REF \
    +-	"[--count=<count>] [--shell|--perl|--python|--tcl]\n" \
    +-	"                         [(--sort=<key>)...] [--format=<format>]\n" \
    +-	"                         [--include-root-refs] [ --stdin | <pattern>... ]\n" \
    +-	"                         [--points-at=<object>]\n" \
    +-	"                         [--merged[=<object>]] [--no-merged[=<object>]]\n" \
    +-	"                         [--contains[=<object>]] [--no-contains[=<object>]]\n" \
    +-	"                         [--exclude=<pattern> ...]"
    +-
     -static char const * const for_each_ref_usage[] = {
    --	N_("git for-each-ref [<options>] [<pattern>]"),
    --	N_("git for-each-ref [--points-at <object>]"),
    --	N_("git for-each-ref [--merged [<commit>]] [--no-merged [<commit>]]"),
    --	N_("git for-each-ref [--contains [<commit>]] [--no-contains [<commit>]]"),
    +-	"git for-each-ref " COMMON_USAGE_FOR_EACH_REF,
     -	NULL
     -};
     -
    @@ for-each-ref.h (new)
     +#ifndef FOR_EACH_REF_H
     +#define FOR_EACH_REF_H
     +
    ++struct repository;
    ++
     +/*
     + * Shared usage string for options common to git-for-each-ref(1)
     + * and git-refs-list(1). The command-specific part (e.g., "git refs list ")
    @@ for-each-ref.h (new)
     +		      struct repository *repo, const char *const *usage);
     +
     +#endif /* FOR_EACH_REF_H */
    -
    - ## t/t0450/adoc-help-mismatches ##
    -@@ t/t0450/adoc-help-mismatches: fast-export
    - fast-import
    - fetch-pack
    - fmt-merge-msg
    --for-each-ref
    - format-patch
    - fsck-objects
    - fsmonitor--daemon
3:  1a15cd454b = 4:  97088dab96 builtin/refs: add list subcommand
4:  29c41d682b = 5:  abe9df9c4f t6300: refactor tests to be shareable
5:  0fd1f714c9 = 6:  a037a47dcd t: add test for git refs list subcommand