[PATCH 0/9] refs: add a '--required' flag to 'git refs optimize'

[Karthik Nayak <karthik.188@gmail.com>]

At GitLab, we use a transaction manager in Gitaly (our service layer on
top of Git) to manage incoming requests. This provides snapshotting
capabilities and provides ACID properties. To optimize for performance,
read snapshots are shared. This means they are cheaper to initiate than
write snapshots. However, housekeeping requires a write snapshot.

Currently, we run housekeeping in write snapshots which includes
optimizing references. If Git exposed information regarding if
optimization was required, then we could spawn a read snapshot to check
if optimization was required and only spawn a write snapshot if needed.

This patch series adds a '--required' flag to 'git refs optimize' which
will indicate if optimization is required for the reference backend or
not.

The series is structured as follows:

Patches 1-4 are mostly cleanup patches, cleaning up existing code post
the addition of 'git refs optimize'. Some of them could be potentially
dropped.

Patch 5 fixes the test which checks for inconsisten leading whitespaces
in our documentation for builtin commands to also consider subcommands.

Patches 6-8 are preliminary patches which add the required changes to
provide a functionality which only checks if optimization is required
without running it.

Patch 9 adds the '--required' flag.

The series is based on top of 60f3f52f17 (The sixteenth batch,
2025-10-08) with 'ps/ref-peeled-tags' merged in.

Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
---
 Documentation/git-pack-refs.adoc     |  1 +
 Documentation/git-refs.adoc          |  1 +
 Documentation/pack-refs-options.adoc |  5 +++++
 builtin/pack-refs.c                  |  2 +-
 builtin/refs.c                       |  2 +-
 pack-refs.c                          | 19 ++++++++++++-----
 pack-refs.h                          | 10 +++++++--
 refs.c                               | 11 +++++-----
 refs.h                               | 31 +++++++++++++++------------
 refs/debug.c                         | 21 ++++++++++++++----
 refs/files-backend.c                 | 27 ++++++++++++------------
 refs/packed-backend.c                | 19 ++++++++++++++---
 refs/refs-internal.h                 | 11 ++++++----
 refs/reftable-backend.c              | 34 +++++++++++++++++++++++-------
 reftable/reftable-stack.h            |  3 +++
 reftable/stack.c                     | 41 ++++++++++++++++++++++++++----------
 t/pack-refs-tests.sh                 | 21 +++++++++++++++++-
 t/t0450-txt-doc-vs-help.sh           | 28 +++++++++++++-----------
 t/t0601-reffiles-pack-refs.sh        |  2 ++
 t/t1463-refs-optimize.sh             |  2 ++
 t/unit-tests/u-reftable-stack.c      | 12 +++++++++--
 21 files changed, 217 insertions(+), 86 deletions(-)

Karthik Nayak (9):
      refs: move to using the '.optimize' functions
      refs: cleanup code around optimization
      refs: rename 'pack_refs_opts' to 'optimize_refs_opts'
      t/pack-refs-tests: move the 'test_done' to callees
      t/t0450: split whitespace consistency check per subcommand
      reftable/stack: return stack segments directly
      reftable/stack: add function to check if optimization is required
      refs: add a `optimize_required` field to `struct ref_storage_be`
      refs: add a '--required' flag to 'git refs optimize'



base-commit: 9081ca56692a28ce89a49537e6c568b3ccdef405
change-id: 20250926-562-add-option-to-check-if-reference-backend-needs-repacking-aa600eb3e055

Thanks
- Karthik