On Thu, Jul 17, 2025 at 3:50 AM Meet Soni <meetsoni3017@xxxxxxxxx> 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@xxxxxx> > Mentored-by: shejialuo <shejialuo@xxxxxxxxx> > Mentored-by: Karthik Nayak <karthik.188@xxxxxxxxx> > Signed-off-by: Meet Soni <meetsoni3017@xxxxxxxxx> > --- > 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.
