Subject: [GSoC][PATCH v3 0/9] Add refs optimize subcommand

From: Meet Soni <[email-masked]>
Date: Thu, 18 Sep 2025 11:16:55 +0530

Hi everyone,

This series introduces `git refs optimize` as a modern replacement for
`git pack-refs`, continuing the effort to consolidate commands
under the `git refs` namespace.

Changes in v3:
- Reworked the entire series from scratch to implement the
  architectural feedback provided by Junio in the v2 review.
- Instead of a simple UI alias, this version introduces a generic,
  backend-agnostic `refs_optimize()` API.
- Added implementations for both the 'files' backend (packing) and
  the 'reftable' backend (compaction).

Meet Soni (9):
  refs: add a generic 'optimize' API
  files-backend: implement 'optimize' action
  reftable-backend: implement 'optimize' action
  builtin/pack-refs: convert to use the generic refs_optimize() API
  builtin/pack-refs: factor out core logic into a shared library
  doc: pack-refs: factor out common options
  builtin/refs: add optimize subcommand
  t0601: refactor tests to be shareable
  t: add test for git refs optimize subcommand

 Documentation/git-pack-refs.adoc     |  53 +---
 Documentation/git-refs.adoc          |  10 +
 Documentation/pack-refs-options.adoc |  52 ++++
 Makefile                             |   1 +
 builtin/pack-refs.c                  |  54 +---
 builtin/refs.c                       |  17 ++
 meson.build                          |   1 +
 pack-refs.c                          |  56 ++++
 pack-refs.h                          |  23 ++
 refs.c                               |   7 +
 refs.h                               |   6 +
 refs/files-backend.c                 |  10 +
 refs/refs-internal.h                 |   3 +
 refs/reftable-backend.c              |   7 +
 t/meson.build                        |   3 +-
 t/pack-refs-tests.sh                 | 431 +++++++++++++++++++++++++++
 t/t0601-reffiles-pack-refs.sh        | 430 +-------------------------
 t/t1463-refs-optimize.sh             |  17 ++
 18 files changed, 650 insertions(+), 531 deletions(-)
 create mode 100644 Documentation/pack-refs-options.adoc
 create mode 100644 pack-refs.c
 create mode 100644 pack-refs.h
 create mode 100644 t/pack-refs-tests.sh
 create mode 100755 t/t1463-refs-optimize.sh

Range-diff against v2:
 -:  ---------- >  1:  a837ae6f5d refs: add a generic 'optimize' API
 -:  ---------- >  2:  e0613b14b6 files-backend: implement 'optimize' action
 -:  ---------- >  3:  ae8d2d29d9 reftable-backend: implement 'optimize' action
 -:  ---------- >  4:  a8cba8a355 builtin/pack-refs: convert to use the generic refs_optimize() API
 1:  67a9187b59 !  5:  ec1085ccd8 builtin/pack-refs: factor out core logic into a shared library
    @@ builtin/pack-refs.c
     -	if (!pack_refs_opts.includes->nr)
     -		string_list_append(pack_refs_opts.includes, "refs/tags/*");
     -
    --	ret = refs_pack_refs(get_main_ref_store(repo), &pack_refs_opts);
    --
    +-	ret = refs_optimize(get_main_ref_store(repo), &pack_refs_opts);
    + 
     -	clear_ref_exclusions(&excludes);
     -	string_list_clear(&included_refs, 0);
     -	string_list_clear(&option_excluded_refs, 0);
    @@ pack-refs.c (new)
     +	if (!pack_refs_opts.includes->nr)
     +		string_list_append(pack_refs_opts.includes, "refs/tags/*");
     +
    -+	ret = refs_pack_refs(get_main_ref_store(repo), &pack_refs_opts);
    ++	ret = refs_optimize(get_main_ref_store(repo), &pack_refs_opts);
     +
     +	clear_ref_exclusions(&excludes);
     +	string_list_clear(&included_refs, 0);
 2:  422eaa0c8b !  6:  e1758816bf doc: factor out common option
    @@ Metadata
     Author: Meet Soni <[email-masked]>
     
      ## Commit message ##
    -    doc: factor out common option
    +    doc: pack-refs: factor out common options
     
         In preparation for adding documentation for `git refs optimize`, factor
         out the common options from the `git-pack-refs` man page into a
         shareable file `pack-refs-options.adoc` and update `git-pack-refs.adoc`
         to use an `include::` macro.
     
    -    This change is a pure refactoring and results in no change to the
    -    final rendered documentation for `pack-refs`.
    +    This change is a pure refactoring and results in no change to the final
    +    rendered documentation for `pack-refs`.
     
         Mentored-by: Patrick Steinhardt <[email-masked]>
         Mentored-by: shejialuo <[email-masked]>
    @@ Documentation/git-pack-refs.adoc: unpacked.
     -+
     -When used with `--include`, refs provided to `--include`, minus refs that are
     -provided to `--exclude` will be packed.
    --
     +include::pack-refs-options.adoc[]
      
    + 
      BUGS
    - ----
     
      ## Documentation/pack-refs-options.adoc (new) ##
     @@
 3:  067a2baa97 !  7:  e3a908fe72 builtin/refs: add optimize subcommand
    @@ Commit message
     
         As part of the ongoing effort to consolidate reference handling,
         introduce a new `optimize` subcommand. This command provides the same
    -    functionality and exit-code behavior as `git pack-refs`, serving
    -    as its modern replacement.
    +    functionality and exit-code behavior as `git pack-refs`, serving as its
    +    modern replacement.
     
         Implement `cmd_refs_optimize` by having it call the `pack_refs_core()`
         helper function. This helper was factored out of the original
    -    `cmd_pack_refs` in a preceding commit, allowing both commands to
    -    share the same core logic as independent peers.
    +    `cmd_pack_refs` in a preceding commit, allowing both commands to share
    +    the same core logic as independent peers.
     
         Add documentation for the new command. The man page leverages the shared
         options file, created in a previous commit, by using the AsciiDoc
    @@ Documentation/git-refs.adoc
     @@ Documentation/git-refs.adoc: git refs list [--count=<count>] [--shell|--perl|--python|--tcl]
      		   [--contains[=<object>]] [--no-contains[=<object>]]
      		   [(--exclude=<pattern>)...] [--start-after=<marker>]
    - 		   [ --stdin | <pattern>... ]
    + 		   [ --stdin | (<pattern>...)]
     +git refs optimize [--all] [--no-prune] [--auto] [--include <pattern>] [--exclude <pattern>]
      
      DESCRIPTION
    @@ builtin/refs.c: static int cmd_refs_list(int argc, const char **argv, const char
     +		REFS_OPTIMIZE_USAGE,
     +		NULL
     +	};
    ++
     +	return pack_refs_core(argc, argv, prefix, repo, refs_optimize_usage);
     +}
     +
 4:  640ebd9a4f !  8:  4f63632ac2 t0601: refactor tests to be shareable
    @@ Commit message
         variable and then sourcing the test library.
     
         This new structure follows the established pattern used for sharing
    -    tests between `git-for-each-ref` and `git-refs list` and prepares the test suite
    -    for the `refs optimize` tests to be added in a subsequent commit.
    +    tests between `git-for-each-ref` and `git-refs list` and prepares the
    +    test suite for the `refs optimize` tests to be added in a subsequent
    +    commit.
     
         Mentored-by: Patrick Steinhardt <[email-masked]>
         Mentored-by: shejialuo <[email-masked]>
 5:  37ca586bb9 =  9:  39eed2831a t: add test for git refs optimize subcommand

base-commit: f814da676ae46aac5be0a98b99373a76dee6cedb
-- 
2.34.1