Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
git maintenance run [--task=<task>]... [--auto] [--schedule=<frequency>] [--quiet]
git maintenance register | unregister | start | stop

Try it

Bash Run individual tasks and see their effect

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.

Bash Registering a repository and the default schedule

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

Terminal
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.repo values; the scheduled job loops over it. Moving a repository requires unregister and register again.
  • Cron on Linux. start edits your user crontab between marker comments; on systems with systemd it prefers timers. Review the result with crontab -l.
  • Two-step loose-object cleanup. The loose-objects task 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 fetch afterwards is almost instant.
  • gc.auto still applies to repositories not under register. With register, Git stops running gc --auto after 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-graph and the multi-pack-index. scalar turns all of this on for you.