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.
Using this in CI
CI checkouts are shallow and detached by default, which changes the answer this command gives you. Commands that read history, branch names, or tags need the checkout configured for it.
- uses: actions/checkout@v4
with:
fetch-depth: 0 # history, tags, and git describe all need this
- run: |
git rev-parse --is-shallow-repository # expect false
git rev-parse --abbrev-ref HEAD # prints HEAD when detached