[GSoC][PATCH v6 0/6] Add refs list subcommand

Hello everyone,

This is the sixth version of the patch series that introduces the git refs list subcommand.

changes in v6:
  - rebased onto v2.51.0-rc0

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 |   88 +
 Documentation/git-for-each-ref.adoc     |   89 +-
 Documentation/git-refs.adoc             |   16 +
 builtin/for-each-ref.c                  |   36 +-
 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, 2316 insertions(+), 2244 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 v5:
1:  d2fa47a2b9 ! 1:  fd4959594c doc: factor out common option
    @@ Documentation/for-each-ref-options.adoc (new)
     +
     +--include-root-refs::
     +	List root refs (HEAD and pseudorefs) apart from regular refs.
    ++
    ++--start-after=<marker>::
    ++    Allows paginating the output by skipping references up to and including the
    ++    specified marker. When paging, it should be noted that references may be
    ++    deleted, modified or added between invocations. Output will only yield those
    ++    references which follow the marker lexicographically. Output begins from the
    ++    first reference that would come after the marker alphabetically. Cannot be
    ++    used with `--sort=<key>` or `--stdin` options, or the _<pattern>_ argument(s)
    ++    to limit the refs.
     
      ## Documentation/git-for-each-ref.adoc ##
     @@ Documentation/git-for-each-ref.adoc: host language allowing their direct evaluation in that language.
    @@ Documentation/git-for-each-ref.adoc: host language allowing their direct evaluat
     -
     ---include-root-refs::
     -	List root refs (HEAD and pseudorefs) apart from regular refs.
    +-
    +---start-after=<marker>::
    +-    Allows paginating the output by skipping references up to and including the
    +-    specified marker. When paging, it should be noted that references may be
    +-    deleted, modified or added between invocations. Output will only yield those
    +-    references which follow the marker lexicographically. Output begins from the
    +-    first reference that would come after the marker alphabetically. Cannot be
    +-    used with `--sort=<key>` or `--stdin` options, or the _<pattern>_ argument(s)
    +-    to limit the refs.
     +include::for-each-ref-options.adoc[]
      
      FIELD NAMES
2:  48a006dca9 ! 2:  1ed0717f6b builtin/for-each-ref: align usage string with the man page
    @@ builtin/for-each-ref.c
     +#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" \
    ++	"                         [--include-root-refs] [--points-at=<object>]\n" \
     +	"                         [--merged[=<object>]] [--no-merged[=<object>]]\n" \
     +	"                         [--contains[=<object>]] [--no-contains[=<object>]]\n" \
    -+	"                         [--exclude=<pattern> ...]"
    ++	"                         [(--exclude=<pattern>)...] [--start-after=<marker>]\n" \
    ++	"                         [ --stdin | <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>]]"),
    +-	N_("git for-each-ref [--start-after <marker>]"),
     +	"git for-each-ref " COMMON_USAGE_FOR_EACH_REF,
      	NULL
      };
3:  b7788d477a ! 3:  69f147aa12 builtin/for-each-ref: factor out core logic into a helper
    @@ Commit message
     
      ## builtin/for-each-ref.c ##
     @@
    - #include "builtin.h"
      #include "commit.h"
      #include "config.h"
    + #include "environment.h"
     +#include "for-each-ref.h"
      #include "gettext.h"
      #include "object.h"
    @@ builtin/for-each-ref.c
     -#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" \
    +-	"                         [--include-root-refs] [--points-at=<object>]\n" \
     -	"                         [--merged[=<object>]] [--no-merged[=<object>]]\n" \
     -	"                         [--contains[=<object>]] [--no-contains[=<object>]]\n" \
    --	"                         [--exclude=<pattern> ...]"
    +-	"                         [(--exclude=<pattern>)...] [--start-after=<marker>]\n" \
    +-	"                         [ --stdin | <pattern>... ]"
     -
     -static char const * const for_each_ref_usage[] = {
     -	"git for-each-ref " COMMON_USAGE_FOR_EACH_REF,
    @@ builtin/for-each-ref.c: int cmd_for_each_ref(int argc,
     -		usage_with_options(for_each_ref_usage, opts);
     +		usage_with_options(usage, opts);
      
    - 	sorting = ref_sorting_options(&sorting_options);
    - 	ref_sorting_set_sort_flags_all(sorting, REF_SORTING_ICASE, icase);
    + 	if (filter.start_after && sorting_options.nr > 1)
    + 		die(_("cannot use --start-after with custom sort options"));
     @@ builtin/for-each-ref.c: int cmd_for_each_ref(int argc,
      	strvec_clear(&vec);
      	return 0;
    @@ for-each-ref.h (new)
     +#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" \
    ++	"                         [--include-root-refs] [--points-at=<object>]\n" \
     +	"                         [--merged[=<object>]] [--no-merged[=<object>]]\n" \
     +	"                         [--contains[=<object>]] [--no-contains[=<object>]]\n" \
    -+	"                         [--exclude=<pattern> ...]"
    ++	"                         [(--exclude=<pattern>)...] [--start-after=<marker>]\n" \
    ++	"                         [ --stdin | <pattern>... ]"
     +
     +/*
     + * The core logic for for-each-ref and its clones.
4:  97088dab96 ! 4:  4195415eb5 builtin/refs: add list subcommand
    @@ Documentation/git-refs.adoc: 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] [ --stdin | <pattern>... ]
    -+	      [--points-at=<object>]
    -+	      [--merged[=<object>]] [--no-merged[=<object>]]
    -+	      [--contains[=<object>]] [--no-contains[=<object>]]
    -+	      [--exclude=<pattern> ...]
    ++		   [(--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
      -----------
5:  abe9df9c4f = 5:  d3da47e950 t6300: refactor tests to be shareable
6:  a037a47dcd = 6:  df2c3fc720 t: add test for git refs list subcommand