@matheusbsbs / matheus-bagliano / commits / eecccfe98b

builtin/refs: add list subcommand

Git's reference management is distributed across multiple commands. As part of an ongoing effort to consolidate and modernize reference handling, introduce a `list` subcommand under the `git refs` umbrella as a replacement for `git for-each-ref`. Implement `cmd_refs_list` by having it call the `for_each_ref_core()` helper function. This helper was factored out of the original `cmd_for_each_ref` in a preceding commit, allowing both commands to share the same core logic as independent peers. Add documentation for the new command. The man page leverages the shared options file, created in a previous commit, by using the AsciiDoc `include::` macro to ensure consistency with git-for-each-ref(1). Mentored-by: Patrick Steinhardt <ps@pks.im> Mentored-by: shejialuo <shejialuo@gmail.com> Mentored-by: Karthik Nayak <karthik.188@gmail.com> Signed-off-by: Meet Soni <meetsoni3017@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>

Meet Soni committed Aug 5, 2025 at 14:57 UTC eecccfe98bb023a79f3c2b8bc415b6d656d0d381
2 files changed +30
Documentation/git-refs.adoc
+16
@@ -11,6 +11,13 @@ SYNOPSIS
11 [synopsis]
12 git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]
13 git refs verify [--strict] [--verbose]
14 +git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
15 + [(--sort=<key>)...] [--format=<format>]
16 + [--include-root-refs] [--points-at=<object>]
17 + [--merged[=<object>]] [--no-merged[=<object>]]
18 + [--contains[=<object>]] [--no-contains[=<object>]]
19 + [(--exclude=<pattern>)...] [--start-after=<marker>]
20 + [ --stdin | <pattern>... ]
21
22 DESCRIPTION
23 -----------
@@ -26,6 +33,11 @@ migrate::
33 verify::
34 Verify reference database consistency.
35
36 +list::
37 + List references in the repository with support for filtering,
38 + formatting, and sorting. This subcommand is an alias for
39 + linkgit:git-for-each-ref[1] and offers identical functionality.
40 +
41 OPTIONS
42 -------
43
@@ -57,6 +69,10 @@ The following options are specific to 'git refs verify':
69 --verbose::
70 When verifying the reference database consistency, be chatty.
71
72 +The following options are specific to 'git refs list':
73 +
74 +include::for-each-ref-options.adoc[]
75 +
76 KNOWN LIMITATIONS
77 -----------------
78
builtin/refs.c
+14
@@ -6,6 +6,7 @@
6 #include "refs.h"
7 #include "strbuf.h"
8 #include "worktree.h"
9 +#include "for-each-ref.h"
10
11 #define REFS_MIGRATE_USAGE \
12 N_("git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]")
@@ -101,6 +102,17 @@ static int cmd_refs_verify(int argc, const char **argv, const char *prefix,
102 return ret;
103 }
104
105 +static int cmd_refs_list(int argc, const char **argv, const char *prefix,
106 + struct repository *repo)
107 +{
108 + static char const * const refs_list_usage[] = {
109 + N_("git refs list " COMMON_USAGE_FOR_EACH_REF),
110 + NULL
111 + };
112 +
113 + return for_each_ref_core(argc, argv, prefix, repo, refs_list_usage);
114 +}
115 +
116 int cmd_refs(int argc,
117 const char **argv,
118 const char *prefix,
@@ -109,12 +121,14 @@ int cmd_refs(int argc,
121 const char * const refs_usage[] = {
122 REFS_MIGRATE_USAGE,
123 REFS_VERIFY_USAGE,
124 + "git refs list " COMMON_USAGE_FOR_EACH_REF,
125 NULL,
126 };
127 parse_opt_subcommand_fn *fn = NULL;
128 struct option opts[] = {
129 OPT_SUBCOMMAND("migrate", &fn, cmd_refs_migrate),
130 OPT_SUBCOMMAND("verify", &fn, cmd_refs_verify),
131 + OPT_SUBCOMMAND("list", &fn, cmd_refs_list),
132 OPT_END(),
133 };
134