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 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 (local)

Thanks!

Patrick

---
Patrick Steinhardt (9):
      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: 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                          | 278 ++++++++++++++++++++++++++++------
 t/t7900-maintenance.sh                | 246 ++++++++++++++++++++++++++++++
 3 files changed, 515 insertions(+), 58 deletions(-)

Range-diff versus v1:

 1:  d16d9ac4f01 =  1:  f14cf90529d builtin/gc: remove global `repack` variable
 2:  2beb7edfdc1 =  2:  64fde2d3fb0 builtin/gc: make `too_many_loose_objects()` reusable without GC config
 3:  e4bcc347e76 !  3:  9ba24540238 builtin/maintenance: introduce "geometric-repack" task
    @@ t/t7900-maintenance.sh: test_expect_success 'maintenance.incremental-repack.auto
     +	rm -f "trace2.txt" &&
     +	GIT_TRACE2_EVENT="$(pwd)/trace2.txt" \
     +		git maintenance run --task=geometric-repack 2>/dev/null &&
    -+	test_subcommand git repack -d -l --geometric=2 --quiet --write-midx <trace2.txt &&
    ++	test_subcommand git repack -d -l --geometric=2 \
    ++		--quiet --write-midx <trace2.txt &&
     +
     +	# Verify that the number of packfiles matches our expectation.
     +	ls -l .git/objects/pack/*.pack >packfiles &&
    @@ t/t7900-maintenance.sh: test_expect_success 'maintenance.incremental-repack.auto
     +		run_and_verify_geometric_pack 2 &&
     +
     +		# Both packfiles have 3 objects, so the next run would cause us
    -+		# to merge both packfiles together. This should be turned into
    ++		# to merge all packfiles together. This should be turned into
     +		# an all-into-one-repack.
     +		GIT_TRACE2_EVENT="$(pwd)/all-into-one-repack.txt" \
     +			git maintenance run --task=geometric-repack 2>/dev/null &&
    @@ t/t7900-maintenance.sh: test_expect_success 'maintenance.incremental-repack.auto
     +
     +test_geometric_repack_needed () {
     +	NEEDED="$1"
    -+	AUTO_LIMIT="$2" &&
    ++	GEOMETRIC_CONFIG="$2" &&
     +	rm -f trace2.txt &&
     +	GIT_TRACE2_EVENT="$(pwd)/trace2.txt" \
    -+		git ${AUTO_LIMIT:+-c maintenance.geometric-repack.auto=$AUTO_LIMIT} maintenance run --auto --task=geometric-repack &&
    ++		git ${GEOMETRIC_CONFIG:+-c maintenance.geometric-repack.$GEOMETRIC_CONFIG} \
    ++		maintenance run --auto --task=geometric-repack 2>/dev/null &&
     +	case "$NEEDED" in
     +	true)
     +		test_grep "\[\"git\",\"repack\"," trace2.txt;;
    @@ t/t7900-maintenance.sh: test_expect_success 'maintenance.incremental-repack.auto
     +		# An empty repository does not need repacking, except when
     +		# explicitly told to do it.
     +		test_geometric_repack_needed false &&
    -+		test_geometric_repack_needed false 0 &&
    -+		test_geometric_repack_needed false 1 &&
    -+		test_geometric_repack_needed true -1 &&
    ++		test_geometric_repack_needed false auto=0 &&
    ++		test_geometric_repack_needed false auto=1 &&
    ++		test_geometric_repack_needed true auto=-1 &&
     +
     +		test_oid_init &&
     +
    @@ t/t7900-maintenance.sh: test_expect_success 'maintenance.incremental-repack.auto
     +		test_commit "$(test_oid blob17_1)" &&
     +		test_geometric_repack_needed false &&
     +		test_commit "$(test_oid blob17_2)" &&
    -+		test_geometric_repack_needed false 257 &&
    -+		test_geometric_repack_needed true 256 &&
    ++		test_geometric_repack_needed false auto=257 &&
    ++		test_geometric_repack_needed true auto=256 &&
     +
     +		# Force another repack.
     +		test_commit first &&
     +		test_commit second &&
    -+		test_geometric_repack_needed true -1 &&
    ++		test_geometric_repack_needed true auto=-1 &&
     +
     +		# We now have two packfiles that would be merged together. As
     +		# such, the repack should always happen unless the user has
     +		# disabled the auto task.
    -+		test_geometric_repack_needed false 0 &&
    -+		test_geometric_repack_needed true 9000
    ++		test_geometric_repack_needed false auto=0 &&
    ++		test_geometric_repack_needed true auto=9000
     +	)
     +'
     +
 -:  ----------- >  4:  d1b805004b9 builtin/maintenance: make the geometric factor configurable
 4:  c9a6e576299 =  5:  d6fa70640c2 builtin/maintenance: don't silently ignore invalid strategy
 5:  3c82a91f152 =  6:  37f7793dab9 builtin/maintenance: run maintenance tasks depending on type
 6:  78502ad6868 =  7:  4b15eac845c builtin/maintenance: extend "maintenance.strategy" to manual maintenance
 7:  59a5450c44f =  8:  eb75881b6ae builtin/maintenance: make "gc" strategy accessible
 8:  51065b109fa =  9:  5c011e7a7e2 builtin/maintenance: introduce "geometric" strategy

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