From: Meet Soni <meetsoni3017@gmail•com>
To: git@vger•kernel.org
Cc: ps@pks•im, shejialuo@gmail•com, karthik.188@gmail•com,
gitster@pobox•com, sunshine@sunshineco•com,
phillip.wood123@gmail•com, Meet Soni <meetsoni3017@gmail•com>,
John Cai <johncai86@gmail•com>
Subject: [GSoC][PATCH v6 4/6] builtin/refs: add list subcommand
Date: Tue, 5 Aug 2025 14:57:56 +0530 [thread overview]
Message-ID: <20250805092758.5321-5-meetsoni3017@gmail.com> (raw)
In-Reply-To: <20250805092758.5321-1-meetsoni3017@gmail.com>
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>
---
Documentation/git-refs.adoc | 16 ++++++++++++++++
builtin/refs.c | 14 ++++++++++++++
2 files changed, 30 insertions(+)
diff --git a/Documentation/git-refs.adoc b/Documentation/git-refs.adoc
index 4d6dc994f9..e608980711 100644
--- a/Documentation/git-refs.adoc
+++ b/Documentation/git-refs.adoc
@@ -11,6 +11,13 @@ SYNOPSIS
[synopsis]
git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]
git refs verify [--strict] [--verbose]
+git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
+ [(--sort=<key>)...] [--format=<format>]
+ [--include-root-refs] [--points-at=<object>]
+ [--merged[=<object>]] [--no-merged[=<object>]]
+ [--contains[=<object>]] [--no-contains[=<object>]]
+ [(--exclude=<pattern>)...] [--start-after=<marker>]
+ [ --stdin | <pattern>... ]
DESCRIPTION
-----------
@@ -26,6 +33,11 @@ migrate::
verify::
Verify reference database consistency.
+list::
+ List references in the repository with support for filtering,
+ formatting, and sorting. This subcommand is an alias for
+ linkgit:git-for-each-ref[1] and offers identical functionality.
+
OPTIONS
-------
@@ -57,6 +69,10 @@ 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':
+
+include::for-each-ref-options.adoc[]
+
KNOWN LIMITATIONS
-----------------
diff --git a/builtin/refs.c b/builtin/refs.c
index c7ad0a2963..76224feba4 100644
--- a/builtin/refs.c
+++ b/builtin/refs.c
@@ -6,6 +6,7 @@
#include "refs.h"
#include "strbuf.h"
#include "worktree.h"
+#include "for-each-ref.h"
#define REFS_MIGRATE_USAGE \
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,
return ret;
}
+static int cmd_refs_list(int argc, const char **argv, const char *prefix,
+ struct repository *repo)
+{
+ static char const * const refs_list_usage[] = {
+ N_("git refs list " COMMON_USAGE_FOR_EACH_REF),
+ NULL
+ };
+
+ return for_each_ref_core(argc, argv, prefix, repo, refs_list_usage);
+}
+
int cmd_refs(int argc,
const char **argv,
const char *prefix,
@@ -109,12 +121,14 @@ int cmd_refs(int argc,
const char * const refs_usage[] = {
REFS_MIGRATE_USAGE,
REFS_VERIFY_USAGE,
+ "git refs list " COMMON_USAGE_FOR_EACH_REF,
NULL,
};
parse_opt_subcommand_fn *fn = NULL;
struct option opts[] = {
OPT_SUBCOMMAND("migrate", &fn, cmd_refs_migrate),
OPT_SUBCOMMAND("verify", &fn, cmd_refs_verify),
+ OPT_SUBCOMMAND("list", &fn, cmd_refs_list),
OPT_END(),
};
--
2.34.1
next prev parent reply other threads:[~2025-08-05 9:28 UTC|newest]
Thread overview: 65+ messages / expand[flat|nested] mbox.gz Atom feed top
2025-06-27 7:49 [GSoC][RFC PATCH 0/2] Add refs list subcommand Meet Soni
2025-06-27 7:49 ` [GSoC][RFC PATCH 1/2] builtin/refs: add " Meet Soni
2025-06-27 16:27 ` Jean-Noël Avila
2025-06-27 18:13 ` Junio C Hamano
2025-06-30 4:28 ` Meet Soni
2025-06-29 11:05 ` [PATCH] doc:git-for-each-ref: fix styling and typos Jean-Noël Avila
2025-06-30 15:48 ` Junio C Hamano
2025-06-30 18:55 ` Jean-Noël AVILA
2025-06-27 7:49 ` [GSoC][RFC PATCH 2/2] t: add test for git refs list subcommand Meet Soni
2025-06-27 18:03 ` [GSoC][RFC PATCH 0/2] Add " Junio C Hamano
2025-06-28 8:05 ` shejialuo
2025-06-30 14:05 ` Junio C Hamano
2025-07-06 12:58 ` shejialuo
2025-06-30 3:53 ` Meet Soni
2025-06-30 20:10 ` Junio C Hamano
2025-07-09 13:36 ` Patrick Steinhardt
2025-07-17 7:50 ` [GSoC][RFC PATCH v2 " Meet Soni
2025-07-17 7:50 ` [GSoC][RFC PATCH v2 1/2] builtin/refs: add " Meet Soni
2025-07-17 16:48 ` Eric Sunshine
2025-07-23 5:01 ` Meet Soni
2025-07-17 7:50 ` [GSoC][RFC PATCH v2 2/2] t: add test for git refs " Meet Soni
2025-07-17 21:01 ` Junio C Hamano
2025-07-23 5:17 ` Meet Soni
2025-07-23 15:03 ` Junio C Hamano
2025-07-23 6:43 ` [GSoC][RFC PATCH v3 0/3] Add " Meet Soni
2025-07-23 6:43 ` [GSoC][RFC PATCH v3 1/3] builtin/refs: add " Meet Soni
2025-07-24 5:58 ` Patrick Steinhardt
2025-07-24 16:01 ` Junio C Hamano
2025-07-25 11:10 ` Meet Soni
2025-07-23 6:43 ` [GSoC][RFC PATCH v3 2/3] t6300: refactor tests to be shareable Meet Soni
2025-07-23 6:43 ` [GSoC][RFC PATCH v3 3/3] t: add test for git refs list subcommand Meet Soni
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 0/5] Add " Meet Soni
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 1/5] doc: factor out common option Meet Soni
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 2/5] builtin/for-each-ref: factor out core logic into a helper Meet Soni
2025-08-01 5:54 ` Patrick Steinhardt
2025-08-04 6:34 ` Meet Soni
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 3/5] builtin/refs: add list subcommand Meet Soni
2025-08-01 13:27 ` Phillip Wood
2025-08-01 14:43 ` Junio C Hamano
2025-08-01 15:49 ` Phillip Wood
2025-08-01 17:14 ` Junio C Hamano
2025-08-04 9:28 ` Phillip Wood
2025-08-04 6:32 ` Meet Soni
2025-08-04 9:27 ` Phillip Wood
2025-08-04 15:35 ` Junio C Hamano
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 4/5] t6300: refactor tests to be shareable Meet Soni
2025-07-31 9:00 ` [GSoC][RFC PATCH v4 5/5] t: add test for git refs list subcommand Meet Soni
2025-08-01 5:54 ` [GSoC][RFC PATCH v4 0/5] Add " Patrick Steinhardt
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 0/6] " Meet Soni
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 1/6] doc: factor out common option Meet Soni
2025-08-04 18:34 ` Junio C Hamano
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 2/6] builtin/for-each-ref: align usage string with the man page Meet Soni
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 3/6] builtin/for-each-ref: factor out core logic into a helper Meet Soni
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 4/6] builtin/refs: add list subcommand Meet Soni
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 5/6] t6300: refactor tests to be shareable Meet Soni
2025-08-04 9:22 ` [GSoC][RFC PATCH v5 6/6] t: add test for git refs list subcommand Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 0/6] Add " Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 1/6] doc: factor out common option Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 2/6] builtin/for-each-ref: align usage string with the man page Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 3/6] builtin/for-each-ref: factor out core logic into a helper Meet Soni
2025-08-05 9:27 ` Meet Soni [this message]
2025-08-05 9:27 ` [GSoC][PATCH v6 5/6] t6300: refactor tests to be shareable Meet Soni
2025-08-05 9:27 ` [GSoC][PATCH v6 6/6] t: add test for git refs list subcommand Meet Soni
2025-08-05 13:07 ` [GSoC][PATCH v6 0/6] Add " Patrick Steinhardt
2025-08-05 16:12 ` Junio C Hamano
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20250805092758.5321-5-meetsoni3017@gmail.com \
--to=meetsoni3017@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(echo .)com \
--cc=johncai86@gmail$(echo .)com \
--cc=karthik.188@gmail$(echo .)com \
--cc=phillip.wood123@gmail$(echo .)com \
--cc=ps@pks$(echo .)im \
--cc=shejialuo@gmail$(echo .)com \
--cc=sunshine@sunshineco$(echo .)com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox