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>
Subject: [GSoC][RFC PATCH v5 0/6] Add refs list subcommand
Date: Mon, 4 Aug 2025 14:52:49 +0530 [thread overview]
Message-ID: <20250804092255.1092973-1-meetsoni3017@gmail.com> (raw)
In-Reply-To: <20250731090040.1625303-1-meetsoni3017@gmail.com>
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
--
2.34.1
next prev parent reply other threads:[~2025-08-04 9:23 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 ` Meet Soni [this message]
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 ` [GSoC][PATCH v6 4/6] builtin/refs: add list subcommand Meet Soni
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=20250804092255.1092973-1-meetsoni3017@gmail.com \
--to=meetsoni3017@gmail$(echo .)com \
--cc=git@vger$(echo .)kernel.org \
--cc=gitster@pobox$(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