Re: [GSoC][RFC PATCH v3 1/3] builtin/refs: add list subcommand

From: Meet Soni <meetsoni3017@gmail.com>
Date: Jul 25, 2025, 11:10 UTC
Message-ID: <CAPhwyn1XK8SoW_EM+EnaaxWsQ8QTYVkMxBZqCQa0-YutvNVJZA@mail.gmail.com>
In-Reply-To: <aIHLdkhdVNy72Yf-@pks.im>

On Thu, 24 Jul 2025 at 11:28, Patrick Steinhardt <ps@pks.im> wrote:

Show 11 quoted lines

>
> On Wed, Jul 23, 2025 at 12:13:11PM +0530, Meet Soni wrote:
> > diff --git a/Documentation/git-for-each-ref.adoc b/Documentation/git-for-each-ref.adoc
> > index 5ef89fc0fe..f7bbc1902a 100644
> > --- a/Documentation/git-for-each-ref.adoc
> > +++ b/Documentation/git-for-each-ref.adoc
>
> Tiny nit, not worth a reroll by itself: it would have been nice to move
> the extraction of the common options from our docs into a separate,
> preparatory commit.
>

I'll do it in the next version.

Show 25 quoted lines

> > diff --git a/builtin/for-each-ref.c b/builtin/for-each-ref.c
> > index 3d2207ec77..d7d8279049 100644
> > --- a/builtin/for-each-ref.c
> > +++ b/builtin/for-each-ref.c
> > @@ -16,11 +16,27 @@ static char const * const for_each_ref_usage[] = {
> >       NULL
> >  };
> >
> > +#define REFS_LIST_USAGE \
> > +     N_("git refs list [--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 refs_list_usage[] = {
> > +     REFS_LIST_USAGE,
> > +     NULL
> > +};
>
> Shouldn't the usage strings for git-for-each-ref(1) and git-refs-list(1)
> be the same, except for the command name?
>

I thought so too, but the man page of git-for-each-ref(1) and the code implementation differ. And the test didn't capture it as it's marked as a "known breakage", will update this in the next version.

Show 46 quoted lines

> >  int cmd_for_each_ref(int argc,
> >                    const char **argv,
> >                    const char *prefix,
> >                    struct repository *repo)
> >  {
> > +     int cmd_is_refs_list = !strcmp(argv[0], "refs list");
> > +     const char *const *opt_usage = cmd_is_refs_list ? refs_list_usage : for_each_ref_usage;
> >       struct ref_sorting *sorting;
> >       struct string_list sorting_options = STRING_LIST_INIT_DUP;
> >       int icase = 0, include_root_refs = 0, from_stdin = 0;
>
> This follows the same pattern we have in "builtin/blame.c". It's not
> exactly pretty that git-for-each-ref(1) is aware of git-refs(1) now, but
> I think it's the pragmatic thing to do.
>
> > diff --git a/builtin/refs.c b/builtin/refs.c
> > index 998d2a2c1c..41e29d1b5f 100644
> > --- a/builtin/refs.c
> > +++ b/builtin/refs.c
> > @@ -13,6 +14,15 @@
> >  #define REFS_VERIFY_USAGE \
> >       N_("git refs verify [--strict] [--verbose]")
> >
> > +#define REFS_LIST_USAGE \
> > +     N_("git refs list [--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 int cmd_refs_migrate(int argc, const char **argv, const char *prefix,
> >                           struct repository *repo UNUSED)
> >  {
>
> Hm, this one is a bit unfortunate though, as it feels like it's just a
> matter of time before the two `REFS_LIST_USAGE` defines drift apart.
> Might be worth it to move them to a shared place.
>
> Alternatively, we could pull out the logic of `cmd_for_each_ref()` into
> a separate function that also receives the usage array. Not sure whether
> that is worth the hassle though.
>
> Another alternative would be to just say `git refs list [<options>]`.
> This here

True. The first two suggestions seem the right way forward. The third one, just using a generic git refs list [<options>] seems counter-productive, as a key goal here is to improve discoverability, and hiding the full list of options would work against that.

The solution of pulling the core logic into a helper function seems like the most robust approach, and since Junio's feedback also points in that direction, I'll proceed with that refactoring.

Thanks.