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

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