Hello everyone,
This is the fourth version of the patch series that introduces the git
refs list subcommand.
Changes in v4:
- Implemented architectural refactoring. The core logic of
for-each-ref now resides in a shared helper function, and both
for-each-ref and refs list have been simplified to thin wrappers
around it.
- The usage strings have also been refactored. The common options
are now defined in a shared macro in a new for-each-ref.h header.
- The patch series has been further split to cleanly separate the
preparatory refactoring commits (for both the C code and the
AsciiDoc documentation) from the commit that introduces the new
feature.
- As a beneficial side-effect of unifying the usage strings, this
series now fixes a pre-existing inconsistency between the --help
output and the man page for for-each-ref. This allows a known
breakage for it in the t0450 documentation test to be removed.
---
(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 (5):
doc: factor out common option
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 | 24 +
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, 2305 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 v3:
1: 547b0bbf8f < -: ---------- builtin/refs: add list subcommand
-: ---------- > 1: d2fa47a2b9 doc: factor out common option
-: ---------- > 2: 5084db4d14 builtin/for-each-ref: factor out core logic into a helper
-: ---------- > 3: 1a15cd454b builtin/refs: add list subcommand
2: 5d5057ff98 = 4: 29c41d682b t6300: refactor tests to be shareable
3: b9cb9cdf48 = 5: 0fd1f714c9 t: add test for git refs list subcommand
--
2.34.1
