[PATCH v4 00/10] builtin/maintenance: introduce "geometric" strategy

Hi,

by default, git-maintenance(1) uses git-gc(1) to perform repository housekeeping. This tool has a couple of shortcomings, most importantly that it regularly does all-into-one repacks. This doesn't really work all that well in the context of monorepos, where you really want to avoid repacking all objects regularly.

An alternative maintenance strategy is the "incremental" strategy, but this strategy has two downsides:

  - Strategies in general only apply to scheduled maintenance. So if you
    run git-maintenance(1), you still end up with git-gc(1).

  - The strategy is designed to not ever delete any data, but a full
    replacment for git-gc(1) needs to also prune reflogs, rereree caches
    and vanished worktrees.

This patch series aims to fix both of these issues.

First, the series introduces a new "geometric" maintenance task, which makes use of geometric repacking as exposed by git-repack(1) in the general case. In the case where a geometric repack ends up merging all packfiles into one we instead do an all-into-one repack with cruft packs so that we can still phase out objects over time.

Second, the series extends maintenance strategies to also cover normal maintenance. If the user has configured the "geometric" strategy, we'll thus use it for both manual and scheduled maintenance. For backwards compatibility, the "incremental" strategy is changed so that it uses git-gc(1) for manual maintenance and the other tasks for scheduled maintenance.

The series is built on top of b660e2dcb9 (Sync with 'maint', 2025-10-14) with tb/incremental-midx-part-3.1 at c886af90f8 (SQUASH??? play well with other topics by preemptively including "repository.h", 2025-09-29) merged into it.

Changes in v4:
  - Fix a flaky test because git-repack(1) always decides to rewrite the
    MIDX, even though no packs have changed. This isn't a new issue, and
    other maintenance tasks behave the same. So I decided to punt on it
    for now.
  - Link to v3: https://lore.kernel.org/r/20251024-pks-maintenance-geometric-strategy-v3-0-9b5b3bdb4387@pks.im

Changes in v3:
  - More line wrapping.
  - Improve readability of maintenance strategies by using nested
    designated initializers.
  - Use git-count-object(1) to count loose objects.
  - Link to v2: https://lore.kernel.org/r/20251021-pks-maintenance-geometric-strategy-v2-0-f0d727832b80@pks.im

Changes in v2:
  - Make the geometric factor configurable via
    "maintenance.geometric-repack.splitFactor".
  - Wrap some overly long lines in our tests.
  - Link to v1: https://lore.kernel.org/r/20251016-pks-maintenance-geometric-strategy-v1-0-18943d474203@pks.im

Thanks!

Patrick

---
Patrick Steinhardt (10):
      builtin/gc: remove global `repack` variable
      builtin/gc: make `too_many_loose_objects()` reusable without GC config
      builtin/maintenance: introduce "geometric-repack" task
      builtin/maintenance: make the geometric factor configurable
      builtin/maintenance: don't silently ignore invalid strategy
      builtin/maintenance: improve readability of strategies
      builtin/maintenance: run maintenance tasks depending on type
      builtin/maintenance: extend "maintenance.strategy" to manual maintenance
      builtin/maintenance: make "gc" strategy accessible
      builtin/maintenance: introduce "geometric" strategy

 Documentation/config/maintenance.adoc |  49 +++++-
 builtin/gc.c                          | 313 ++++++++++++++++++++++++++++------
 t/t7900-maintenance.sh                | 245 ++++++++++++++++++++++++++
 3 files changed, 544 insertions(+), 63 deletions(-)

Range-diff versus v3:

 1:  e1af6298ba2 =  1:  9893494c0f7 builtin/gc: remove global `repack` variable
 2:  3009eb5fa82 =  2:  d9214040c96 builtin/gc: make `too_many_loose_objects()` reusable without GC config
 3:  888f8576a8f !  3:  0aa6444cef2 builtin/maintenance: introduce "geometric-repack" task
    @@ t/t7900-maintenance.sh: test_expect_success 'maintenance.incremental-repack.auto
     +
     +		# Repacking should now cause a no-op geometric repack because
     +		# no packfiles need to be combined.
    -+		ls -l .git/objects/pack >before &&
    ++		ls -l .git/objects/pack/*.pack >before &&
     +		run_and_verify_geometric_pack 1 &&
    -+		ls -l .git/objects/pack >after &&
    ++		ls -l .git/objects/pack/*.pack >after &&
     +		test_cmp before after &&
     +
     +		# This incremental change creates a new packfile that only
 4:  d14b6d9bfc7 =  4:  ccff4aea2fe builtin/maintenance: make the geometric factor configurable
 5:  0b2e1dc2561 =  5:  594ee7d3765 builtin/maintenance: don't silently ignore invalid strategy
 6:  417554d8c89 =  6:  cc5844dd05e builtin/maintenance: improve readability of strategies
 7:  0c7f246a9f3 =  7:  6ce5c3bf93a builtin/maintenance: run maintenance tasks depending on type
 8:  4e01332152f =  8:  bbbaee0d13e builtin/maintenance: extend "maintenance.strategy" to manual maintenance
 9:  cf8adf2e039 =  9:  f4faf84e06e builtin/maintenance: make "gc" strategy accessible
10:  20bfc9802d7 = 10:  fc65b12ed9e builtin/maintenance: introduce "geometric" strategy

--- base-commit: 0bb2c786c2349dd6700727153c13d81cbfb41710 change-id: 20251015-pks-maintenance-geometric-strategy-580c58581b01