Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Configuration Options

maintenance.* settings

Reference for the maintenance.* settings: maintenance.auto, maintenance.strategy, per-task enabled and schedule values, and maintenance.repo for scheduled upkeep.

The maintenance.* variables configure git maintenance, the successor to a bare git gc for keeping repositories fast. Instead of one monolithic collection, maintenance is a set of small tasks (rebuild the commit-graph, prefetch remote branches, repack loose objects, and so on) that can run on different schedules, often in the background through your operating system's scheduler.

You use these settings to pick a strategy, switch individual tasks on or off, and choose how often each one runs. They are read from the repository and global configuration.

Terminal
git config maintenance.strategy incremental
git config maintenance.prefetch.enabled false
git config maintenance.gc.schedule weekly
git maintenance run --task=commit-graph

Try it

Bash Run a single task and see its 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.

The loose-objects task first deletes loose objects that are already in a pack, then packs up to 50,000 of the remaining ones. In the run above the four commits were packed (packs: 1) and commit-graphs appeared under .git/objects/info; the loose copies are removed by the next run, which is why count did not drop yet.

Bash Strategy, task switches and registration

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 config maintenance.auto <true | false>
git config maintenance.strategy <none | incremental>
git config maintenance.<task>.enabled <true | false>
git config maintenance.<task>.schedule <hourly | daily | weekly>
git config --global --add maintenance.repo <path>
git config maintenance.<task>.auto <number>
Setting Description
maintenance.auto Whether commands such as commit and fetch may run git maintenance run --auto in the background. Default true. git maintenance register sets it to false locally, because the scheduler takes over.
maintenance.strategy A preset that decides which tasks are enabled and how often they run. incremental turns on commit-graph, prefetch, loose-objects and incremental-repack (hourly or daily) and turns the full gc task off; none enables nothing by default.
maintenance.<task>.enabled Overrides the strategy for one task.
maintenance.<task>.schedule How often the scheduler runs the task. The --schedule option of git maintenance run selects the tasks due at that frequency.
maintenance.repo A multi-valued key in global (or system) configuration listing the repositories that the scheduled run visits. Managed by register and unregister.
maintenance.<task>.auto For the gc, loose-objects and incremental-repack tasks, the threshold that --auto uses to decide whether any work is needed.

The task names are gc, commit-graph, prefetch, loose-objects, incremental-repack, pack-refs, reflog-expire, worktree-prune and rerere-gc. With no --task option and no strategy, git maintenance run runs the gc task only.

Edge cases: a task you name explicitly with --task=<name> always runs, even if enabled is false. schedule and --schedule only matter for scheduled runs.

Usage notes

  • Maintenance and gc.* are related, not the same. The gc task runs git gc, so the gc.* settings still apply to it. With the incremental strategy the gc task is off, and the other tasks keep the repository tidy in smaller steps.
  • git maintenance start installs the scheduler (launchd, systemd timers, schtasks, cron or a user-supplied one, chosen with --scheduler) and also registers the current repository. git maintenance stop removes it. These need access to the operating system, so they are not shown in the runnable examples.
  • Prefetch is safe. The prefetch task downloads new objects into refs/prefetch/ rather than changing your remote-tracking branches, so a later git fetch is fast and your branch views do not shift under you.
  • Large repositories benefit most. The commit-graph speeds up git log --graph and merge-base computations, and incremental repacking avoids rewriting one huge pack. Small repositories rarely notice a difference.
  • One schedule list per user. maintenance.repo lives in your global config, so register works from any repository and unregister --force can remove paths that no longer exist.
  • Version notes: git maintenance appeared in Git 2.29 with the incremental strategy following shortly after. The pack-refs, reflog-expire, worktree-prune and rerere-gc tasks are newer; run git maintenance run --help on older installations to see which tasks exist.