Add refs list subcommand
Subsystems (2)
cover Add refs list subcommand
This patch series introduces the git refs list subcommand, as part of a longer-term goal to consolidate and modernize ref listing functionality currently split between git-show-ref(1) and git-for-each-ref(1).
The initial implementation focuses on mirroring the behavior of git-show-ref, providing support for filtering by --branches, --tags, and --head, and implementing pattern matching similar to the legacy command. This ensures backward compatibility.
That said, git-for-each-ref(1) offers more flexible pattern matching and we acknowledge that its style may be a better fit in the long run. As such, this RFC deliberately starts with the show-ref matching semantics to solicit feedback on whether to switch to for-each-ref style matching as the default, with a compatibility flag to preserve legacy behavior.
It's also worth highlighting that several options from git-show-ref are intended to be supported in the git refs list subcommand. These include flags such as '--abbrev', '--quiet', '--dereference', '--hash', and '--exclude-existing'. While this series focuses on core functionality and pattern matching, these additional options are within scope for future patches.
Additionally, the git-for-each-ref(1) command offers a rich set of features that would be valuable to incorporate into git refs list. At this point, all of its existing options appear to provide meaningful functionality, and my current thinking is to support them incrementally as part of expanding this subcommand. I'd appreciate feedback on whether there are any options that should be reconsidered or excluded in this consolidation effort.
This RFC is meant to start a broader discussion on:
- The desired default behavior of pattern matching in git refs list
- Which features from both git-show-ref and git-for-each-ref should be preserved, rethought, or dropped
- How much backward compatibility we want to offer, and through what interface (e.g., compatibility flags)
Feedback and thoughts on these topics would be very welcome.
Meet Soni (2):
builtin/refs: add list subcommand
t: add tests for refs list subcommand
Documentation/git-refs.adoc | 25 ++++++++ builtin/refs.c | 110 ++++++++++++++++++++++++++++++++++++ t/meson.build | 1 + t/t1461-refs-list.sh | 95 +++++++++++++++++++++++++++++++ 4 files changed, 231 insertions(+) create mode 100755 t/t1461-refs-list.sh
Signature · 1 line
2.34.1
RFC PATCH 1/2 builtin/refs: add list subcommand
Git's reference management is distributed across multiple commands and as part of an ongoing effort to streamline and modernize reference handling, we are beginning to consolidate these operations into a cohesive git refs command.
Add a list subcommand to git refs as a modern replacement for git show-ref, consolidating ref listing functionality under the unified git refs command.
The initial implementation supports the following options from git show-ref:
- --head
- --tags
- --branches
- patterns argument
For large changes, this patch limits itself to the basic ref listing and commonly used flags. Remaining options will be added incrementally in follow-up patches, guided by feedback from the mailing list.
--- Documentation/git-refs.adoc | 25 ++++++++ builtin/refs.c | 110 ++++++++++++++++++++++++++++++++++++ 2 files changed, 135 insertions(+)
Documentation/git-refs.adoc +25 -0
@@ -11,6 +11,7 @@ SYNOPSIS [synopsis] git refs migrate --ref-format=<format> [--no-reflog] [--dry-run] git refs verify [--strict] [--verbose] +git refs list [--head] [--branches] [--tag] [--] [<pattern>...] DESCRIPTION -----------
@@ -26,6 +27,12 @@ migrate:: verify:: Verify reference database consistency. +list:: + Displays references available in a local repository along with the associated + commit IDs. Results can be filtered using a pattern. + + By default, shows the tags, heads, and remote refs. + OPTIONS -------
@@ -57,6 +64,24 @@ The following options are specific to 'git refs verify': --verbose:: When verifying the reference database consistency, be chatty. +The following options are specific to 'git refs list': + +--head:: + Show the HEAD reference, even if it would normally be filtered out. + +--branches:: +--tags:: + Limit to local branches and local tags, respectively. These options + are not mutually exclusive; when given both, references stored in + "refs/heads" and "refs/tags" are displayed. + +<pattern>...:: + Show references matching one or more patterns. Patterns are matched from + the end of the full name, and only complete parts are matched, e.g. + 'master' matches 'refs/heads/master', 'refs/remotes/origin/master', + 'refs/tags/jedi/master' but not 'refs/heads/mymaster' or + 'refs/remotes/master/jedi'. + KNOWN LIMITATIONS -----------------
builtin/refs.c +110 -0
140 lines not on this page · raw message
Signature · 1 line
2.34.1
RFC PATCH 2/2 t: add tests for refs list subcommand
In reply to Meet SoniTest the implemented functionality of git refs list and verify backward compatibility with git show-ref for the supported flags and patterns.
--- t/meson.build | 1 + t/t1461-refs-list.sh | 95 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 96 insertions(+) create mode 100755 t/t1461-refs-list.sh
t/meson.build +1 -0
@@ -224,6 +224,7 @@ integration_tests = [ 't1450-fsck.sh', 't1451-fsck-buffer.sh', 't1460-refs-migrate.sh', + 't1461-refs-list.sh', 't1500-rev-parse.sh', 't1501-work-tree.sh', 't1502-rev-parse-parseopt.sh',
t/t1461-refs-list.sh new file +95 -0
95 lines not on this page · raw message
Signature · 1 line
2.34.1
Quoted 11 lines · Meet Soni
This RFC is meant to start a broader discussion on:
- The desired default behavior of pattern matching in git refs list
- Which features from both git-show-ref and git-for-each-ref should be preserved, rethought, or dropped
- How much backward compatibility we want to offer, and through what interface (e.g., compatibility flags)
Feedback and thoughts on these topics would be very welcome.
In addition to these three points, 0th point perhaps is "Is it desirable to unify these two commands in the first place?"
I only use "show-ref" when I care about a single ref in a script, expecting to be able to switch on its exit status. Everything else I'd use for-each-ref.
But then that particular unique advantage of show-ref over for-each-ref can be done with "rev-parse --verify".
So, I'd rather not to see yet another command to do the same thing. Rather, is it insufficient to just use for-each-ref or rev-parse, let the sleeping show-ref alone, and be happy?
Quoted 10 lines
Meet Soni (2):
builtin/refs: add list subcommand
t: add tests for refs list subcommandDocumentation/git-refs.adoc | 25 ++++++++ builtin/refs.c | 110 ++++++++++++++++++++++++++++++++++++ t/meson.build | 1 + t/t1461-refs-list.sh | 95 +++++++++++++++++++++++++++++++ 4 files changed, 231 insertions(+) create mode 100755 t/t1461-refs-list.sh
Quoted 22 lines · Junio C Hamano
Quoted 11 lines · Meet Soni
This RFC is meant to start a broader discussion on:
- The desired default behavior of pattern matching in git refs list
- Which features from both git-show-ref and git-for-each-ref should be preserved, rethought, or dropped
- How much backward compatibility we want to offer, and through what interface (e.g., compatibility flags)
Feedback and thoughts on these topics would be very welcome.
In addition to these three points, 0th point perhaps is "Is it desirable to unify these two commands in the first place?"
I only use "show-ref" when I care about a single ref in a script, expecting to be able to switch on its exit status. Everything else I'd use for-each-ref.
Quoted 6 lines
But then that particular unique advantage of show-ref over for-each-ref can be done with "rev-parse --verify".
So, I'd rather not to see yet another command to do the same thing. Rather, is it insufficient to just use for-each-ref or rev-parse, let the sleeping show-ref alone, and be happy?
The broader motivation behind this effort (and the overarching GSoC project) has been to reduce fragmentation in ref-related functionality by gradually consolidating it under the git refs umbrella, aiming for consistency and discoverability.
Your point about rev-parse --verify covering show-ref's main utility is well taken. If that truly makes show-ref redundant, then perhaps it makes more sense to focus consolidation efforts around for-each-ref instead.
One concern I have is that if we simply replicate for-each-ref under a new name, we may still face the same question: what does this new command add that the old one doesn't already handle?
I'd love to hear thoughts on what a modernized or simplified ref-listing interface could look like. Are there features or changes worth exploring that could justify the consolidation?
Thanks,
Meet