Git Reference ยท Configuration Options
gc.* settings
Reference for the gc.* settings: gc.auto, gc.autoDetach, gc.pruneExpire, gc.reflogExpire and gc.aggressiveDepth, and how they decide what git gc keeps and removes.
The gc.* variables control git gc, Git's housekeeping command, and the automatic runs of it that many commands trigger. Garbage collection packs loose objects into packfiles, packs references, removes objects nobody refers to any more, and expires old reflog entries. These settings decide when it starts by itself and how long unreachable data is kept as a safety net.
Most people never change them. You reach for them when automatic collection interrupts you at a bad moment, when a repository grows large, or when you need to keep (or really delete) old objects.
git config gc.auto 6700 # loose-object threshold for automatic gc git config gc.autoDetach false # run automatic gc in the foreground git config gc.pruneExpire 2.weeks.ago git config gc.reflogExpire 90.days
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.
In the second example the commit survived the first gc even with --prune=now: the HEAD reflog still pointed at it, and git gc keeps such entries for 30 days (gc.reflogExpireUnreachable). Only after that reflog entry was expired could the object be pruned. (This example uses the real clock, because reflog ages are measured from the dates recorded in them.)
Syntax
git config gc.<name> <value> git config gc.<pattern>.reflogExpire <time> git gc [--aggressive] [--auto] [--prune=<date>] [--cruft] [--keep-largest-pack]
| Setting | Default | Description |
|---|---|---|
gc.auto |
6700 |
Approximate number of loose objects that triggers an automatic gc. 0 disables automatic gc. |
gc.autoPackLimit |
50 |
Number of packfiles that triggers a repack that merges them. 0 disables the check. |
gc.autoDetach |
true |
Let automatic gc finish in the background after the command that started it. |
gc.bigPackThreshold |
0 (off) |
Packs at least this size are left out of repacking (like --keep-largest-pack). |
gc.pruneExpire |
2.weeks.ago |
Age after which unreachable loose objects are deleted. now deletes all of them at once; never keeps them. |
gc.reflogExpire |
90.days |
How long reachable reflog entries are kept. |
gc.reflogExpireUnreachable |
30.days |
How long reflog entries whose commits are no longer in the branch history are kept. |
gc.<pattern>.reflogExpire |
(inherits) | Same, for refs matching the pattern (for example refs/stash). |
gc.aggressiveDepth |
50 |
Delta chain depth used by git gc --aggressive. |
gc.aggressiveWindow |
250 |
Delta search window used by git gc --aggressive. |
gc.packRefs |
true |
Whether gc packs references (notbare limits it to non-bare repositories). |
gc.cruftPacks |
true |
Collect unreachable objects into a "cruft pack" rather than exploding them into loose files (default since Git 2.38 when gc is run). |
gc.writeCommitGraph |
true |
Update the commit-graph file during gc. |
gc.worktreePruneExpire |
3.months.ago |
Age after which stale worktree administrative data is pruned. |
gc.logExpiry |
1.day |
How long a gc.log error file blocks further automatic runs. |
Edge cases: gc.auto is tested by counting objects in one of the 256 object sub-directories and scaling, so it is a rough trigger, not an exact count. If automatic gc fails, Git writes .git/gc.log and refuses to start another automatic run until the file expires or you delete it.
Usage notes
- Automatic runs are triggered by other commands (
commit,merge,fetch,rebaseand others), and printAuto packing the repository for optimum performanceunless run quietly. Since Git 2.29 the defaultgc.autoDetachmakes the collection continue after the command returns, which is why you may see disk activity afterward. - Disable automatic gc with care.
gc.auto 0is common on build servers and in tools that run their own schedule (seemaintenance.*), but a repository that never packs gets slower and larger. Repositories that use scheduled maintenance should let that do the work. - The two grace periods protect you.
git reflogandgc.pruneExpireare why a deleted branch or an amended commit is usually still recoverable for weeks. Lowering them (now) frees disk space immediately and makes recovery impossible; do that only on purpose, for example when removing a leaked secret. --aggressiveis rarely worth it. It recomputes all deltas withgc.aggressiveWindow/aggressiveDepthand can take very long on big repositories for a modest saving. Once after a big import is plenty.- Concurrency:
git gc --autotakes a lock, so a second automatic run does not start while one is active. A crash can leavegc.pid; Git ignores a stale one after a while. - Cruft packs keep unreachable objects and their modification times in a single file. That avoids creating thousands of loose objects and still lets the grace period work.
- Servers: hosting software normally runs its own repack and prune schedule. A bare repository can use the same settings.