[PATCH v4 0/7] builtin/maintenance: implement missing tasks compared to git-gc(1)

[Patrick Steinhardt <ps@pks.im>]

Hi,

this small patch series implements the last couple of remaining tasks
that are missing compared to the functionality git-gc(1) provides.

Right now, git-maintenance(1) still executes git-gc(1). With these last
gaps plugged though we can in theory fully replace git-gc(1) with finer
grained tasks without losing any functionality. The benefit is that it
becomes possible for users to have finer-grained control over what
exactly the maintenance does.

This patch series doesn't do that yet, but only implements whatever is
needed to get there.

Changes in v2:
  - Introduce "maintenance.worktree-prune.auto", which controls how many
    stale worktrees need to exist before executing `git worktree prune`.
  - Introduce "maintenance.rerere-gc.auto", which controls how many
    stale rerere entries need to exist before executing `git rerere gc`.
  - Add tests to verify that "gc.worktreePruneExpire" works.
  - Remove some fragile test logic by introducing functions that check
    for a given maintenance subprocess.
  - Link to v1: https://lore.kernel.org/r/20250425-pks-maintenance-missing-tasks-v1-0-972ed6ab2c0d@pks.im

Changes in v3:
  - Simplify the heuristic for "rerere-gc" so that we only count the
    number of directory entries in ".git/rr-cache", without considering
    staleness.
  - Link to v2: https://lore.kernel.org/r/20250430-pks-maintenance-missing-tasks-v2-0-2580b7b8ca3a@pks.im

Changes in v4:
  - simplified the heuristic for "rerere-gc" even further. A positive
    value for "maintenance.rerere-gc.auto" now indicates that the
    command will run whenever there is at least one directory entry in
    ".rr-cache". The exact value does not matter anymore.
  - Link to v3: https://lore.kernel.org/r/20250502-pks-maintenance-missing-tasks-v3-0-13e130d36640@pks.im

Thanks!

Patrick

---
Patrick Steinhardt (7):
      builtin/gc: fix indentation of `cmd_gc()` parameters
      builtin/gc: remove global variables where it trivial to do
      builtin/gc: move pruning of worktrees into a separate function
      worktree: expose function to retrieve worktree names
      builtin/maintenance: introduce "worktree-prune" task
      builtin/gc: move rerere garbage collection into separate function
      builtin/maintenance: introduce "rerere-gc" task

 Documentation/config/maintenance.adoc |  17 ++++
 Documentation/git-maintenance.adoc    |   8 ++
 builtin/gc.c                          | 149 +++++++++++++++++++++++++++-------
 builtin/worktree.c                    |  25 +++---
 t/t7900-maintenance.sh                | 115 ++++++++++++++++++++++++++
 worktree.c                            |  30 +++++++
 worktree.h                            |   8 ++
 7 files changed, 308 insertions(+), 44 deletions(-)

Range-diff versus v3:

1:  0cf3cb937c3 = 1:  6614504400b builtin/gc: fix indentation of `cmd_gc()` parameters
2:  5982d47cc95 = 2:  6c8c66282c5 builtin/gc: remove global variables where it trivial to do
3:  afda176acd3 = 3:  bfa8fc00434 builtin/gc: move pruning of worktrees into a separate function
4:  b3b6a14bf1c = 4:  d87b883cf62 worktree: expose function to retrieve worktree names
5:  e02d59bb944 = 5:  354a1985b4b builtin/maintenance: introduce "worktree-prune" task
6:  cb31ec6b8bd = 6:  6f40349b53f builtin/gc: move rerere garbage collection into separate function
7:  65e8483fe4a ! 7:  e3c9da19a2c builtin/maintenance: introduce "rerere-gc" task
    @@ Documentation/config/maintenance.adoc: maintenance.reflog-expire.auto::
     +	This integer config option controls how often the `rerere-gc` task
     +	should be run as part of `git maintenance run --auto`. If zero, then
     +	the `rerere-gc` task will not run with the `--auto` option. A negative
    -+	value will force the task to run every time. Otherwise, a positive
    -+	value implies the command should run when there are at least this many
    -+	directory entries in the "rr-cache" directory. The default value is 1.
    ++	value will force the task to run every time. Otherwise, any positive
    ++	value implies the command will run when the "rr-cache" directory exists
    ++	and has at least one entry, regardless of whether it is stale or not.
    ++	This heuristic may be refined in the future. The default value is 1.
     +
      maintenance.worktree-prune.auto::
      	This integer config option controls how often the `worktree-prune` task
    @@ builtin/gc.c: static int maintenance_task_rerere_gc(struct maintenance_run_opts
     +
     +	/*
     +	 * We skip garbage collection in case we either have no "rr-cache"
    -+	 * directory or when it doesn't contain at least as many directories as
    -+	 * indicated by "maintenance.rerere-gc.auto".
    ++	 * directory or when it doesn't contain at least one entry.
     +	 */
     +	repo_git_path_replace(the_repository, &path, "rr-cache");
     +	dir = opendir(path.buf);
     +	if (!dir)
     +		goto out;
    -+
    -+	while (readdir_skip_dot_and_dotdot(dir)) {
    -+		if (--limit)
    -+			continue;
    -+
    -+		should_gc = 1;
    -+		goto out;
    -+	}
    ++	should_gc = !!readdir_skip_dot_and_dotdot(dir);
     +
     +out:
     +	strbuf_release(&path);
    @@ t/t7900-maintenance.sh: test_expect_success 'worktree-prune task honors gc.workt
     +	# A negative value should always prune.
     +	test_expect_rerere_gc git -c maintenance.rerere-gc.auto=-1 maintenance run --auto --task=rerere-gc &&
     +
    ++	# A positive value prunes when there is at least one entry.
    ++	test_expect_rerere_gc ! git -c maintenance.rerere-gc.auto=9000 maintenance run --auto --task=rerere-gc &&
     +	mkdir .git/rr-cache &&
    ++	test_expect_rerere_gc ! git -c maintenance.rerere-gc.auto=9000 maintenance run --auto --task=rerere-gc &&
     +	: >.git/rr-cache/entry-1 &&
    -+	: >.git/rr-cache/entry-2 &&
    ++	test_expect_rerere_gc git -c maintenance.rerere-gc.auto=9000 maintenance run --auto --task=rerere-gc &&
     +
     +	# Zero should never prune.
    -+	test_expect_rerere_gc ! git -c maintenance.rerere-gc.auto=0 maintenance run --auto --task=rerere-gc &&
    -+	# A positive value should require at least this many stale rerere entries.
    -+	test_expect_rerere_gc ! git -c maintenance.rerere-gc.auto=3 maintenance run --auto --task=rerere-gc &&
    -+	test_expect_rerere_gc git -c maintenance.rerere-gc.auto=2 maintenance run --auto --task=rerere-gc
    ++	: >.git/rr-cache/entry-1 &&
    ++	test_expect_rerere_gc ! git -c maintenance.rerere-gc.auto=0 maintenance run --auto --task=rerere-gc
     +'
     +
      test_expect_success '--auto and --schedule incompatible' '

---
base-commit: a2955b34f48265d240ab8c7deb0a929ec2d65fd0
change-id: 20250424-pks-maintenance-missing-tasks-8ffcdd596b73