1git-gc(1) 2========= 3 4NAME 5---- 6git-gc - Cleanup unnecessary files and optimize the local repository 7 8 9SYNOPSIS 10-------- 11[verse] 12'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack] 13 14DESCRIPTION 15----------- 16Runs a number of housekeeping tasks within the current repository, 17such as compressing file revisions (to reduce disk space and increase 18performance), removing unreachable objects which may have been 19created from prior invocations of 'git add', packing refs, pruning 20reflog, rerere metadata or stale working trees. May also update ancillary 21indexes such as the commit-graph. 22 23When common porcelain operations that create objects are run, they 24will check whether the repository has grown substantially since the 25last maintenance, and if so run `git gc` automatically. See `gc.auto` 26below for how to disable this behavior. 27 28Running `git gc` manually should only be needed when adding objects to 29a repository without regularly running such porcelain commands, to do 30a one-off repository optimization, or e.g. to clean up a suboptimal 31mass-import. See the "PACKFILE OPTIMIZATION" section in 32linkgit:git-fast-import[1] for more details on the import case. 33 34OPTIONS 35------- 36 37--aggressive:: 38 Usually 'git gc' runs very quickly while providing good disk 39 space utilization and performance. This option will cause 40 'git gc' to more aggressively optimize the repository at the expense 41 of taking much more time. The effects of this optimization are 42 mostly persistent. See the "AGGRESSIVE" section below for details. 43 44--auto:: 45 With this option, 'git gc' checks whether any housekeeping is 46 required; if not, it exits without performing any work. 47+ 48See the `gc.auto` option in the "CONFIGURATION" section below for how 49this heuristic works. 50+ 51Once housekeeping is triggered by exceeding the limits of 52configuration options such as `gc.auto` and `gc.autoPackLimit`, all 53other housekeeping tasks (e.g. rerere, working trees, reflog...) will 54be performed as well. 55 56 57--prune=<date>:: 58 Prune loose objects older than date (default is 2 weeks ago, 59 overridable by the config variable `gc.pruneExpire`). 60 --prune=now prunes loose objects regardless of their age and 61 increases the risk of corruption if another process is writing to 62 the repository concurrently; see "NOTES" below. --prune is on by 63 default. 64 65--no-prune:: 66 Do not prune any loose objects. 67 68--quiet:: 69 Suppress all progress reports. 70 71--force:: 72 Force `git gc` to run even if there may be another `git gc` 73 instance running on this repository. 74 75--keep-largest-pack:: 76 All packs except the largest pack and those marked with a 77 `.keep` files are consolidated into a single pack. When this 78 option is used, `gc.bigPackThreshold` is ignored. 79 80AGGRESSIVE 81---------- 82 83When the `--aggressive` option is supplied, linkgit:git-repack[1] will 84be invoked with the `-f` flag, which in turn will pass 85`--no-reuse-delta` to linkgit:git-pack-objects[1]. This will throw 86away any existing deltas and re-compute them, at the expense of 87spending much more time on the repacking. 88 89The effects of this are mostly persistent, e.g. when packs and loose 90objects are coalesced into one another pack the existing deltas in 91that pack might get re-used, but there are also various cases where we 92might pick a sub-optimal delta from a newer pack instead. 93 94Furthermore, supplying `--aggressive` will tweak the `--depth` and 95`--window` options passed to linkgit:git-repack[1]. See the 96`gc.aggressiveDepth` and `gc.aggressiveWindow` settings below. By 97using a larger window size we're more likely to find more optimal 98deltas. 99 100It's probably not worth it to use this option on a given repository 101without running tailored performance benchmarks on it. It takes a lot 102more time, and the resulting space/delta optimization may or may not 103be worth it. Not using this at all is the right trade-off for most 104users and their repositories. 105 106CONFIGURATION 107------------- 108 109The below documentation is the same as what's found in 110linkgit:git-config[1]: 111 112include::config/gc.txt[] 113 114NOTES 115----- 116 117'git gc' tries very hard not to delete objects that are referenced 118anywhere in your repository. In particular, it will keep not only 119objects referenced by your current set of branches and tags, but also 120objects referenced by the index, remote-tracking branches, notes saved 121by 'git notes' under refs/notes/, reflogs (which may reference commits 122in branches that were later amended or rewound), and anything else in 123the refs/* namespace. If you are expecting some objects to be deleted 124and they aren't, check all of those locations and decide whether it 125makes sense in your case to remove those references. 126 127On the other hand, when 'git gc' runs concurrently with another process, 128there is a risk of it deleting an object that the other process is using 129but hasn't created a reference to. This may just cause the other process 130to fail or may corrupt the repository if the other process later adds a 131reference to the deleted object. Git has two features that significantly 132mitigate this problem: 133 134. Any object with modification time newer than the `--prune` date is kept, 135 along with everything reachable from it. 136 137. Most operations that add an object to the database update the 138 modification time of the object if it is already present so that #1 139 applies. 140 141However, these features fall short of a complete solution, so users who 142run commands concurrently have to live with some risk of corruption (which 143seems to be low in practice). 144 145HOOKS 146----- 147 148The 'git gc --auto' command will run the 'pre-auto-gc' hook. See 149linkgit:githooks[5] for more information. 150 151 152SEE ALSO 153-------- 154linkgit:git-prune[1] 155linkgit:git-reflog[1] 156linkgit:git-repack[1] 157linkgit:git-rerere[1] 158 159GIT 160--- 161Part of the linkgit:git[1] suite