Git Reference ยท Setup and Basics
git maintenance command
Reference for git maintenance: run gc, commit-graph, prefetch and repack tasks by hand, register repositories and schedule hourly, daily and weekly upkeep.
git maintenance keeps a repository fast and small by running housekeeping tasks: repacking objects, updating the commit-graph, pruning loose files, prefetching remote branches. You can run the tasks once by hand, or register a repository so that a system scheduler (cron, systemd timers, launchd or Task Scheduler) runs them hourly, daily and weekly in the background.
Unlike git gc, which does everything in one heavy pass, maintenance splits the work into small tasks with their own schedules. That is gentler on big repositories because the expensive full repack is optional.
git maintenance run [--task=<task>]... [--auto] [--schedule=<frequency>] [--quiet] git maintenance register | unregister | start | stop
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
git maintenance run [--auto] [--schedule=hourly|daily|weekly] [--task=<task>]... git maintenance register [--config-file <file>] git maintenance unregister [--force] [--config-file <file>] git maintenance start [--scheduler=auto|crontab|systemd-timer|launchctl|schtasks] git maintenance stop
| Subcommand or option | Description |
|---|---|
run |
Run tasks in the current repository now. Without --task, runs the tasks enabled by configuration (by default only gc). |
--task=<task> |
Run a specific task; repeat to run several, in the given order. |
--auto |
Only run tasks whose conditions say work is needed (for example, enough loose objects). This is how git gc --auto after a commit works. |
--schedule=<freq> |
Run the tasks scheduled for this frequency, used by the scheduler job. |
--quiet / --no-quiet |
Control progress output. |
register |
Add the repository to maintenance.repo in the global configuration, set maintenance.auto=false locally (scheduled jobs replace the automatic gc after commands) and, if you have not chosen one, set maintenance.strategy=incremental. |
unregister |
Remove it from the list. --force ignores a repository that is not registered. |
start |
Register and also install the scheduler entries (hourly job). |
stop |
Remove the scheduler entries (repositories stay registered). |
Tasks:
| Task | What it does |
|---|---|
gc |
Full git gc: repack everything, prune, expire reflogs, pack refs. Heavy. |
commit-graph |
Update the commit-graph file for faster history walks. |
prefetch |
Fetch all remotes into hidden refs/prefetch/ refs, so your next fetch is quick and your tracking branches do not move unexpectedly. |
loose-objects |
Pack loose objects in batches, and prune those already packed. |
incremental-repack |
Consolidate pack files using the multi-pack-index, without a full repack. |
pack-refs |
Pack loose refs. |
reflog-expire |
Expire old reflog entries (Git 2.48 and later). |
worktree-prune |
Remove stale worktree metadata (Git 2.48 and later). |
rerere-gc |
Expire old rerere records (Git 2.48 and later). |
Strategies. With maintenance.strategy = incremental, gc is turned off and the other tasks run on a schedule: commit-graph and prefetch hourly, loose-objects and incremental-repack daily, pack-refs weekly. Override any task with maintenance.<task>.enabled and maintenance.<task>.schedule.
Errors: a failing task makes the command exit nonzero; it tries the remaining tasks anyway. start fails if no usable scheduler exists, which is the case in containers and in this site's runner.
Usage notes
- Registration is global. The list of repositories lives in your global config as multiple
maintenance.repovalues; the scheduled job loops over it. Moving a repository requiresunregisterandregisteragain. - Cron on Linux.
startedits your user crontab between marker comments; on systems with systemd it prefers timers. Review the result withcrontab -l. - Two-step loose-object cleanup. The
loose-objectstask first prunes loose files that are already packed, then packs a new batch, so the loose files only disappear on its next run (see the example). - Prefetch is safe on large teams: it never touches branches you can see, but
git fetchafterwards is almost instant. gc.autostill applies to repositories not underregister. Withregister, Git stops runninggc --autoafter commands, because the scheduled jobs take over.- Locks. A running maintenance holds
maintenance.lock; concurrent runs skip instead of waiting. - Large repositories benefit most from the incremental strategy plus
git commit-graphand the multi-pack-index.scalarturns all of this on for you.