NAME

git-gc - Cleanup unnecessary files and optimize the local repository

SYNOPSIS

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

DESCRIPTION

Runs a number of housekeeping tasks within the current repository,such as compressing file revisions (to reduce disk space and increaseperformance), removing unreachable objects which may have beencreated from prior invocations of git add, packing refs, pruningreflog, rerere metadata or stale working trees. May also update ancillaryindexes such as the commit-graph.

When common porcelain operations that create objects are run, theywill check whether the repository has grown substantially since thelast maintenance, and if so run git gc automatically. See gc.autobelow for how to disable this behavior.

Running git gc manually should only be needed when adding objects toa repository without regularly running such porcelain commands, to doa one-off repository optimization, or e.g. to clean up a suboptimalmass-import. See the "PACKFILE OPTIMIZATION" section ingit-fast-import[1] for more details on the import case.

OPTIONS

  • —aggressive

  • Usually git gc runs very quickly while providing good diskspace utilization and performance. This option will causegit gc to more aggressively optimize the repository at the expenseof taking much more time. The effects of this optimization aremostly persistent. See the "AGGRESSIVE" section below for details.

  • —auto

  • With this option, git gc checks whether any housekeeping isrequired; if not, it exits without performing any work.

See the gc.auto option in the "CONFIGURATION" section below for howthis heuristic works.

Once housekeeping is triggered by exceeding the limits ofconfiguration options such as gc.auto and gc.autoPackLimit, allother housekeeping tasks (e.g. rerere, working trees, reflog…​) willbe performed as well.

  • —prune=

  • Prune loose objects older than date (default is 2 weeks ago,overridable by the config variable gc.pruneExpire).—prune=now prunes loose objects regardless of their age andincreases the risk of corruption if another process is writing tothe repository concurrently; see "NOTES" below. —prune is on bydefault.

  • —no-prune

  • Do not prune any loose objects.

  • —quiet

  • Suppress all progress reports.

  • —force

  • Force git gc to run even if there may be another git gcinstance running on this repository.

  • —keep-largest-pack

  • All packs except the largest pack and those marked with a.keep files are consolidated into a single pack. When thisoption is used, gc.bigPackThreshold is ignored.

AGGRESSIVE

When the —aggressive option is supplied, git-repack[1] willbe invoked with the -f flag, which in turn will pass—no-reuse-delta to git-pack-objects[1]. This will throwaway any existing deltas and re-compute them, at the expense ofspending much more time on the repacking.

The effects of this are mostly persistent, e.g. when packs and looseobjects are coalesced into one another pack the existing deltas inthat pack might get re-used, but there are also various cases where wemight pick a sub-optimal delta from a newer pack instead.

Furthermore, supplying —aggressive will tweak the —depth and—window options passed to git-repack[1]. See thegc.aggressiveDepth and gc.aggressiveWindow settings below. Byusing a larger window size we’re more likely to find more optimaldeltas.

It’s probably not worth it to use this option on a given repositorywithout running tailored performance benchmarks on it. It takes a lotmore time, and the resulting space/delta optimization may or may notbe worth it. Not using this at all is the right trade-off for mostusers and their repositories.

CONFIGURATION

The below documentation is the same as what’s found ingit-config[1]:

  • gc.aggressiveDepth
  • The depth parameter used in the delta compressionalgorithm used by git gc —aggressive. This defaultsto 50, which is the default for the —depth option when—aggressive isn’t in use.

See the documentation for the —depth option ingit-repack[1] for more details.

  • gc.aggressiveWindow
  • The window size parameter used in the delta compressionalgorithm used by git gc —aggressive. This defaultsto 250, which is a much more aggressive window size thanthe default —window of 10.

See the documentation for the —window option ingit-repack[1] for more details.

  • gc.auto
  • When there are approximately more than this many looseobjects in the repository, git gc —auto will pack them.Some Porcelain commands use this command to perform alight-weight garbage collection from time to time. Thedefault value is 6700.

Setting this to 0 disables not only automatic packing based on thenumber of loose objects, but any other heuristic git gc —auto willotherwise use to determine if there’s work to do, such asgc.autoPackLimit.

  • gc.autoPackLimit
  • When there are more than this many packs that are notmarked with *.keep file in the repository, git gc—auto consolidates them into one larger pack. Thedefault value is 50. Setting this to 0 disables it.Setting gc.auto to 0 will also disable this.

See the gc.bigPackThreshold configuration variable below. When inuse, it’ll affect how the auto pack limit works.

  • gc.autoDetach

  • Make git gc —auto return immediately and run in backgroundif the system supports it. Default is true.

  • gc.bigPackThreshold

  • If non-zero, all packs larger than this limit are kept whengit gc is run. This is very similar to —keep-base-packexcept that all packs that meet the threshold are kept, notjust the base pack. Defaults to zero. Common unit suffixes ofk, m, or g are supported.

Note that if the number of kept packs is more than gc.autoPackLimit,this configuration variable is ignored, all packs except the base packwill be repacked. After this the number of packs should go belowgc.autoPackLimit and gc.bigPackThreshold should be respected again.

If the amount of memory estimated for git repack to run smoothly isnot available and gc.bigPackThreshold is not set, the largest packwill also be excluded (this is the equivalent of running git gc with—keep-base-pack).

  • gc.writeCommitGraph

  • If true, then gc will rewrite the commit-graph file whengit-gc[1] is run. When using git gc —autothe commit-graph will be updated if housekeeping isrequired. Default is false. See git-commit-graph[1]for details.

  • gc.logExpiry

  • If the file gc.log exists, then git gc —auto will printits content and exit with status zero instead of runningunless that file is more than gc.logExpiry old. Default is"1.day". See gc.pruneExpire for more ways to specify itsvalue.

  • gc.packRefs

  • Running git pack-refs in a repository renders itunclonable by Git versions prior to 1.5.1.2 over dumbtransports such as HTTP. This variable determines whethergit gc runs git pack-refs. This can be set to notbareto enable it within all non-bare repos or it can be set to aboolean value. The default is true.

  • gc.pruneExpire

  • When git gc is run, it will call prune —expire 2.weeks.ago.Override the grace period with this config variable. The value"now" may be used to disable this grace period and always pruneunreachable objects immediately, or "never" may be used tosuppress pruning. This feature helps prevent corruption whengit gc runs concurrently with another process writing to therepository; see the "NOTES" section of git-gc[1].

  • gc.worktreePruneExpire

  • When git gc is run, it callsgit worktree prune —expire 3.months.ago.This config variable can be used to set a different graceperiod. The value "now" may be used to disable the graceperiod and prune $GIT_DIR/worktrees immediately, or "never"may be used to suppress pruning.

  • gc.reflogExpire

  • gc..reflogExpire

  • git reflog expire removes reflog entries older thanthis time; defaults to 90 days. The value "now" expires allentries immediately, and "never" suppresses expirationaltogether. With "" (e.g."refs/stash") in the middle the setting applies only tothe refs that match the .

  • gc.reflogExpireUnreachable

  • gc..reflogExpireUnreachable
  • git reflog expire removes reflog entries older thanthis time and are not reachable from the current tip;defaults to 30 days. The value "now" expires all entriesimmediately, and "never" suppresses expiration altogether.With "" (e.g. "refs/stash")in the middle, the setting applies only to the refs thatmatch the .

These types of entries are generally created as a result of using gitcommit —amend or git rebase and are the commits prior to the amendor rebase occurring. Since these changes are not part of the currentproject most users will want to expire them sooner, which is why thedefault is more aggressive than gc.reflogExpire.

  • gc.rerereResolved

  • Records of conflicted merge you resolved earlier arekept for this many days when git rerere gc is run.You can also use more human-readable "1.month.ago", etc.The default is 60 days. See git-rerere[1].

  • gc.rerereUnresolved

  • Records of conflicted merge you have not resolved arekept for this many days when git rerere gc is run.You can also use more human-readable "1.month.ago", etc.The default is 15 days. See git-rerere[1].

NOTES

git gc tries very hard not to delete objects that are referencedanywhere in your repository. Inparticular, it will keep not only objects referenced by your current setof branches and tags, but also objects referenced by the index,remote-tracking branches, refs saved by git filter-branch inrefs/original/, reflogs (which may reference commits in branchesthat were later amended or rewound), and anything else in the refs/* namespace.If you are expecting some objects to be deleted and they aren’t, checkall of those locations and decide whether it makes sense in your case toremove those references.

On the other hand, when git gc runs concurrently with another process,there is a risk of it deleting an object that the other process is usingbut hasn’t created a reference to. This may just cause the other processto fail or may corrupt the repository if the other process later adds areference to the deleted object. Git has two features that significantlymitigate this problem:

  • Any object with modification time newer than the —prune date is kept,along with everything reachable from it.

  • Most operations that add an object to the database update themodification time of the object if it is already present so that #1applies.

However, these features fall short of a complete solution, so users whorun commands concurrently have to live with some risk of corruption (whichseems to be low in practice).

HOOKS

The git gc —auto command will run the pre-auto-gc hook. Seegithooks[5] for more information.

SEE ALSO

git-prune[1]git-reflog[1]git-repack[1]git-rerere[1]

GIT

Part of the git[1] suite