Skip to content
Tutorials Center
My learning

Topics

Git Reference ยท Maintenance and Recovery

git gc command

Reference for git gc: what garbage collection does, the --aggressive, --prune and --auto options, gc.* settings, and how it relates to repack, prune and maintenance.

git gc ("garbage collection") tidies up a repository. It packs loose objects into packfiles, packs references, expires old reflog entries, and removes unreachable objects that are old enough to be safe to delete. Run on a big repository it saves disk space and makes later commands faster.

You rarely need to run it by hand: Git starts git gc --auto after commands such as commit, merge, fetch and rebase, and that does nothing until there are enough loose objects or packs. In recent versions this automatic run is performed by git maintenance's gc task.

Terminal
git gc [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--cruft] [--force] [--keep-largest-pack]

Try it

Bash Loose objects become a pack

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 gc keeps recent garbage unless told to prune

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

Option Description
--auto Check gc.auto and gc.autoPackLimit first; exit quietly if nothing needs doing. This is how Git calls it for you.
--aggressive Recompute deltas from scratch with a larger window and depth (gc.aggressiveWindow, gc.aggressiveDepth). Much slower; rarely worth it.
--prune=<date> Delete unreachable loose objects older than <date>. Default is gc.pruneExpire (two weeks ago). Use now to remove everything unreachable.
--no-prune Do not delete any unreachable objects.
--cruft Collect unreachable objects in a "cruft pack" instead of leaving them loose. On by default in current versions (gc.cruftPacks); --no-cruft restores loose files.
--max-cruft-size=<n> Cap the size of cruft packs.
--keep-largest-pack Leave the largest pack alone and repack the rest, for huge repositories.
--force Run even if another gc seems to be running (a stale gc.pid lock).
--quiet Suppress progress.
--detach / --no-detach For --auto: run in the background (default) or the foreground.

What it runs: pack-refs --all --prune, reflog expire --all, repack -d -l (with the options above), prune --expire, worktree prune --expire, rerere gc, and writes the commit-graph when gc.writeCommitGraph is on.

Usage notes

  • Two weeks of grace. Unreachable objects younger than gc.pruneExpire survive. That protects objects another Git process has just created but not yet linked.
  • The reflog keeps things reachable. Commits you have "lost" are retained for gc.reflogExpire (90 days) and gc.reflogExpireUnreachable (30 days). After deleting a leaked secret, expire the reflog and prune with now (see git prune).
  • Auto thresholds: gc.auto (default 6700 loose objects) and gc.autoPackLimit (default 50 packs). Setting gc.auto to 0 disables automatic runs.
  • Not concurrency-safe for pruning. Do not run gc --prune=now while other processes write to the repository.
  • --aggressive is overused. The default is already good, and aggressive deltas can make later incremental repacks less efficient. A normal git gc or repack -a -d after a big import is usually enough.
  • Server repositories often use git maintenance with a geometric repack strategy instead of frequent full gcs.
  • After filter-branch or filter-repo, run git gc --prune=now after expiring the reflog to shrink the repository for real.