# git maintenance: Usage, Options & Common CI Errors

> git maintenance runs and schedules repository upkeep tasks like gc, commit-graph, and prefetch. Reference for run, start, --task, and the background-scheduler caveats.

Source: https://latchkey.dev/learn/command-reference/git-maintenance  
Updated: 2026-06-25

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

```Terminal
git maintenance run
git maintenance run --task=commit-graph
git maintenance run --task=incremental-repack --task=pack-refs
git maintenance start
git maintenance stop
```

## Options

| 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.

```.github/workflows/ci.yml
- 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
```

> `git rev-parse --abbrev-ref HEAD` returns the literal string `HEAD` on a detached checkout rather than a branch name. On GitHub Actions read `github.ref_name` instead; the git command cannot know what it was checked out for.

## FAQ

### git maintenance: Usage, Options & Common CI Errors?

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 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.

---

Latchkey runs CI/CD that repairs its own failures. Agent entry points: https://latchkey.dev/agent.txt, https://latchkey.dev/openapi.json, https://latchkey.dev/llms.txt