From: Eric Sunshine <sunshine@sunshineco.com>
Date: Thu, 17 Jul 2025 16:48:12 GMT
Subject: Re: [GSoC][RFC PATCH v2 1/2] builtin/refs: add list subcommand
Message-ID: <CAPig+cQgeqz9bNQSFRvTmoyFgqAwEKSV=KpK18DSP7FA-4GDPw@mail.gmail.com>
In-Reply-To: <20250717075009.26262-2-meetsoni3017@gmail.com>

On Thu, Jul 17, 2025 at 3:50 AM Meet Soni <meetsoni3017@gmail.com> wrote:
> 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` as a thin wrapper around `cmd_for_each_ref`
> instead of duplicating its logic. Forward all arguments to the existing
> function to ensure behavior is identical.
>
> Add documentation for the new command. To keep the documentation DRY and
> consistent with `git-for-each-ref(1)`, refactor the shared command
> options into a standalone file. Use the AsciiDoc `include::` macro to
> embed these options in both man pages.
>
> This prevents duplication in both code and documentation, ensuring that
> `refs list` benefits from any future fixes to the underlying
> `for-each-ref` machinery and its shared documentation.
>
> 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>
> ---
> diff --git a/Documentation/refs-list-options.adoc b/Documentation/refs-list-options.adoc
> @@ -0,0 +1,80 @@
> +// Shared options for for-each-ref and refs list
> +<pattern>...::
> +       If one or more patterns are given, only refs are shown that
> +       match against at least one pattern, either using fnmatch(3) or
> +       literally, in the latter case matching completely or from the
> +       beginning up to a slash.

Nit: We probably don't want the "// Shared options for..." comment. If
someone needs to know which commands share this documentation, a
suitable "grep" invocation will provide the same information but will
be correct at that point in time, whereas a comment like this one can
become stale over time.