Synopsis

git maintenance start
git maintenance run [--task=<task>]
git maintenance stop

Description

The git maintenance command, introduced in Git 2.29, replaces and extends git gc --auto with scheduled, fine-grained maintenance tasks: prefetch, commit-graph generation, loose-object packing, incremental repack, and pack-refs. Running git maintenance start registers a recurring schedule via cron, launchd, systemd, or Task Scheduler depending on platform.

For server-side or long-lived clones of large repositories, enabling maintenance dramatically improves day-to-day responsiveness. Operations like git status and git log become faster as the commit-graph and reachable-bitmap data are kept fresh.

In day-to-day use, git maintenance integrates closely with shell aliases, editor plugins, and continuous integration. Power users often add aliases that combine flags they always pass, or wrap the command in scripts that enforce team conventions. Output formatting can be customized via Git config — pretty formats, color schemes, and pager behavior are all tunable. When something goes wrong, the first diagnostic step is usually to re-run the command with GIT_TRACE=1 in the environment, which reveals the underlying plumbing calls. For unusual situations, the --help output (git maintenance --help) opens the full manual page with details on every option, including those rarely used in casual workflows but essential for debugging or scripting at scale.

Understanding how git maintenance interacts with the rest of Git's data model — the object database, the index, refs, and the working tree — pays dividends. Each command operates on some subset of these pieces, and knowing which it touches helps predict outcomes and recover from mistakes. Reading the official Git documentation alongside hands-on practice in a throwaway repository is the fastest way to internalize the nuances. Most production issues with Git stem from one of three causes: surprising default behavior, partial network operations, or rewriting history that was already shared. A working mental model of git maintenance's side effects helps avoid all three.

Common Options

Examples

git maintenance start
# Set up background maintenance for this repo

git maintenance run --task=commit-graph
# Update the commit-graph on demand

git maintenance run --task=prefetch
# Fetch upstream objects without updating refs

git maintenance unregister
# Stop scheduled maintenance for this repo

Common Mistakes

Forgetting that start registers a system-wide scheduled task. On shared machines, this might not be what you want; use register in a config file instead. Disabling automatic gc but not enabling maintenance leaves the repo to grow unchecked.

Related Commands

git gc, git commit-graph, git fetch --prefetch, git repack