git maintenance: Usage, Options & Common CI Errors
git maintenance bundles the housekeeping tasks that keep a repository fast.
On large or long-lived repos, maintenance replaces ad hoc gc with targeted, schedulable tasks - commit-graph writes, prefetch, incremental repack - that you can run on demand in CI.
What it does
git maintenance run executes one or more upkeep tasks (gc, commit-graph, prefetch, loose-objects, incremental-repack, pack-refs). git maintenance start registers a background schedule via cron, systemd, or launchd.
Common usage
git maintenance run
git maintenance run --task=commit-graph
git maintenance run --task=incremental-repack --task=pack-refs
git maintenance start
git maintenance stopOptions
| Subcommand / flag | What it does |
|---|---|
| run | Run maintenance tasks now |
| --task=<name> | Run only the named task(s) |
| start / stop | Enable or disable the background scheduler |
| register / unregister | Add/remove the repo from scheduled upkeep |
| --auto | Run only if heuristics say it is needed |
Common errors in CI
git maintenance start needs a working scheduler (cron/systemd/launchd) and is usually pointless on ephemeral runners - prefer git maintenance run --task=... in the job. Running gc-style tasks while another git process holds the repo can race; serialize maintenance with the rest of the pipeline.