git maintenance

Scheduled gc, fetch, commit-graph. The Cron of Git.

🎯 What & why

Schedule background upkeep for repos: gc, fetch, commit-graph, prefetch, loose-objects. Like a Cron config dedicated to keeping a repo healthy.

🧠 Mental model

Maintenance is a runner: it reads maintenance.<task>.enabled config and dispatches the named tasks (gc, commit-graph, prefetch, loose-objects, incremental-repack, pack-refs). Scheduling backs onto cron/launchd/systemd-timers so the OS handles when.

🛠️ Synopsis

git maintenance run [<options>]
git maintenance start [--scheduler=<scheduler>]
git maintenance (stop|register|unregister) [<options>]

🎚️ Switches & options

Flag	What it does
`start`	Enable scheduled maintenance.
`stop`	Disable it.
`run`	Run maintenance tasks now.
`register/unregister`	Add/remove the current repo from the maintenance list.

📦 Subcommands

run [--task=<task>] — Run maintenance tasks now.

$ git maintenance run --task=gc

start [--scheduler=<scheduler>] — Enable scheduled maintenance via cron/launchd/systemd.

$ git maintenance start

stop — Disable scheduled maintenance.

$ git maintenance stop

register [--config-file <file>] — Add the current repo to the maintenance list.

$ git maintenance register

unregister [--force] — Remove the current repo from the maintenance list.

$ git maintenance unregister

💡 Use cases

Large repos that benefit from continuous gc/repack.
Mirrors that should fetch periodically.
Replacing ad-hoc cron scripts.

🧪 Examples

Set up scheduled maintenance.

$ git maintenance start

Run an ad-hoc maintenance pass.

$ git maintenance run --task=gc

🎓 Recommendations

Enable on huge repos (chromium, kernel, monorepos).
Combine with the commit-graph for big log/walk perf wins.

🪤 Common pitfalls

Adds background tasks (cron/systemd) — fine in development, sometimes surprising in CI containers.
Won't help small repos meaningfully.

🔗 Related modules

📝 Quiz

Hit each option, then Check answers. Score is recorded; Next is always open.