git/list[1] front-page[2] threads[3] people[4] search[5] about
 

[PATCH 0/3] builtin/refs: introduce subcommand groups

From
Patrick Steinhardt <ps@pks.im>
Date
Oct 1, 2026, 10:13 UTC
Message-ID
<20261001-b4-pks-parse-options-subcommand-groups-v1-0-01eb2f4a4c32@pks.im>
Hi,

the git-refs(1) command has grown quite a bunch of different subcommands by now. These subcommands can easily be grouped into three categories:

  - Operations that span across the whole reference database (migrate,
    verify, optimize).
  - Operations that read references (list, exists).
  - Operations that write references (create, delete, update, rename).

This patch series thus adapts the parse-options subsystem to support grouping subcommands and then introduces the grouping for git-refs(1). This results in the following output:

  usage: git refs migrate --ref-format=<format> [--no-reflog] [--dry-run]
     or: git refs verify [--strict] [--verbose]
     or: git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
                                  [(--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>...)]
     or: git refs exists <ref>
     or: git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]
     or: git refs create [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value>
     or: git refs delete [--message=<reason>] [--no-deref] <ref> [<old-value>]
     or: git refs update [--message=<reason>] [--no-deref] [--create-reflog] <ref> <new-value> [<old-value>]
     or: git refs rename [--message=<reason>] <old-ref> <new-ref>
  Reference database
      migrate               migrate the reference database to a different format
      verify                verify the consistency of the reference database
      optimize              optimize the reference database
  Reading references
      list                  list references
      exists                check whether a reference exists
  Writing references
      create                create a new reference
      delete                delete a reference
      update                update an existing reference
      rename                rename a reference

I expect that going forward, we'll probably have more use cases where we can use these new capabilities (e.g. an upcoming git-objects(1) command, which is going to be the equivalent to git-refs(1)).

Thanks!
Patrick
---
Patrick Steinhardt (3):
      parse-options: fix completion format when first option is skipped
      parse-options: allow grouping subcommands
      builtin/refs: introduce subcommand groups
 Documentation/git-refs.adoc                    |  2 +-
 Documentation/technical/api-parse-options.adoc | 10 ++++-
 builtin/refs.c                                 | 32 ++++++++-----
 parse-options.c                                | 62 ++++++++++++++------------
 parse-options.h                                |  7 +++
 t/helper/test-parse-options.c                  |  4 +-
 t/t0040-parse-options.sh                       | 16 +++++++
 7 files changed, 92 insertions(+), 41 deletions(-)

--- base-commit: a018953688f1b10bddf91bff8747068f5f4746a4 change-id: 20261001-b4-pks-parse-options-subcommand-groups-59b3f27da06c

Next: Patrick Steinhardt
Message 1 of 14 in “builtin/refs: introduce subcommand groups”
  1. 0/3 builtin/refs: introduce subcommand groupsPatrick Steinhardt, Oct 1, 2026
  2. 1/3 parse-options: fix completion format when first option is skippedPatrick Steinhardt, Oct 1, 2026
  3. Junio C HamanoOct 1, 2026
  4. Patrick SteinhardtOct 2, 2026
  5. 2/3 parse-options: allow grouping subcommandsPatrick Steinhardt, Oct 1, 2026
  6. Junio C HamanoOct 1, 2026
  7. Patrick SteinhardtOct 2, 2026
  8. 3/3 builtin/refs: introduce subcommand groupsPatrick Steinhardt, Oct 1, 2026
  9. Junio C HamanoOct 1, 2026
  10. 0/4 builtin/refs: introduce subcommand groupsPatrick Steinhardt, Oct 2, 2026
  11. 1/4 parse-options: fix completion format when first option is skippedPatrick Steinhardt, Oct 2, 2026
  12. 2/4 parse-options: extract functions to print single optionPatrick Steinhardt, Oct 2, 2026
  13. 3/4 parse-options: allow grouping subcommandsPatrick Steinhardt, Oct 2, 2026
  14. 4/4 builtin/refs: introduce subcommand groupsPatrick Steinhardt, Oct 2, 2026

Read the whole thread, see it on lore, or plain text.

$ cat FOOTERMessages come from the public archive at lore.kernel.org/git, fetched every hour. The front page is chosen and written each morning by an AI editor and can be wrong; the threads themselves are the record. About and API. For agents: an MCP server at https://gitlist.dev/mcp, and any thread, story or person page as Markdown by adding .md to its URL (or sending Accept: text/markdown). Details in /llms.txt.