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 persistent, so this option only needs to be used occasionally; every 43 few hundred changesets or so. 44 45--auto:: 46 With this option, 'git gc' checks whether any housekeeping is 47 required; if not, it exits without performing any work. 48 Some git commands run `git gc --auto` after performing 49 operations that could create many loose objects. Housekeeping 50 is required if there are too many loose objects or too many 51 packs in the repository. 52+ 53If the number of loose objects exceeds the value of the `gc.auto` 54configuration variable, then all loose objects are combined into a 55single pack. Setting the value of `gc.auto` 56to 0 disables automatic packing of loose objects. 57+ 58If the number of packs exceeds the value of `gc.autoPackLimit`, 59then existing packs (except those marked with a `.keep` file 60or over `gc.bigPackThreshold` limit) 61are consolidated into a single pack. 62If the amount of memory estimated for `git repack` to run smoothly is 63not available and `gc.bigPackThreshold` is not set, the largest 64pack will also be excluded (this is the equivalent of running `git gc` 65with `--keep-base-pack`). 66Setting `gc.autoPackLimit` to 0 disables automatic consolidation of 67packs. 68+ 69If houskeeping is required due to many loose objects or packs, all 70other housekeeping tasks (e.g. rerere, working trees, reflog...) will 71be performed as well. 72 73 74--prune=<date>:: 75 Prune loose objects older than date (default is 2 weeks ago, 76 overridable by the config variable `gc.pruneExpire`). 77 --prune=now prunes loose objects regardless of their age and 78 increases the risk of corruption if another process is writing to 79 the repository concurrently; see "NOTES" below. --prune is on by 80 default. 81 82--no-prune:: 83 Do not prune any loose objects. 84 85--quiet:: 86 Suppress all progress reports. 87 88--force:: 89 Force `git gc` to run even if there may be another `git gc` 90 instance running on this repository. 91 92--keep-largest-pack:: 93 All packs except the largest pack and those marked with a 94 `.keep` files are consolidated into a single pack. When this 95 option is used, `gc.bigPackThreshold` is ignored. 96 97CONFIGURATION 98------------- 99 100The optional configuration variable `gc.reflogExpire` can be 101set to indicate how long historical entries within each branch's 102reflog should remain available in this repository. The setting is 103expressed as a length of time, for example '90 days' or '3 months'. 104It defaults to '90 days'. 105 106The optional configuration variable `gc.reflogExpireUnreachable` 107can be set to indicate how long historical reflog entries which 108are not part of the current branch should remain available in 109this repository. These types of entries are generally created as 110a result of using `git commit --amend` or `git rebase` and are the 111commits prior to the amend or rebase occurring. Since these changes 112are not part of the current project most users will want to expire 113them sooner. This option defaults to '30 days'. 114 115The above two configuration variables can be given to a pattern. For 116example, this sets non-default expiry values only to remote-tracking 117branches: 118 119------------ 120[gc "refs/remotes/*"] 121 reflogExpire = never 122 reflogExpireUnreachable = 3 days 123------------ 124 125The optional configuration variable `gc.rerereResolved` indicates 126how long records of conflicted merge you resolved earlier are 127kept. This defaults to 60 days. 128 129The optional configuration variable `gc.rerereUnresolved` indicates 130how long records of conflicted merge you have not resolved are 131kept. This defaults to 15 days. 132 133The optional configuration variable `gc.packRefs` determines if 134'git gc' runs 'git pack-refs'. This can be set to "notbare" to enable 135it within all non-bare repos or it can be set to a boolean value. 136This defaults to true. 137 138The optional configuration variable `gc.writeCommitGraph` determines if 139'git gc' should run 'git commit-graph write'. This can be set to a 140boolean value. This defaults to false. 141 142The optional configuration variable `gc.aggressiveWindow` controls how 143much time is spent optimizing the delta compression of the objects in 144the repository when the --aggressive option is specified. The larger 145the value, the more time is spent optimizing the delta compression. See 146the documentation for the --window option in linkgit:git-repack[1] for 147more details. This defaults to 250. 148 149Similarly, the optional configuration variable `gc.aggressiveDepth` 150controls --depth option in linkgit:git-repack[1]. This defaults to 50. 151 152The optional configuration variable `gc.pruneExpire` controls how old 153the unreferenced loose objects have to be before they are pruned. The 154default is "2 weeks ago". 155 156Optional configuration variable `gc.worktreePruneExpire` controls how 157old a stale working tree should be before `git worktree prune` deletes 158it. Default is "3 months ago". 159 160 161NOTES 162----- 163 164'git gc' tries very hard not to delete objects that are referenced 165anywhere in your repository. In 166particular, it will keep not only objects referenced by your current set 167of branches and tags, but also objects referenced by the index, 168remote-tracking branches, refs saved by 'git filter-branch' in 169refs/original/, or reflogs (which may reference commits in branches 170that were later amended or rewound). 171If you are expecting some objects to be deleted and they aren't, check 172all of those locations and decide whether it makes sense in your case to 173remove those references. 174 175On the other hand, when 'git gc' runs concurrently with another process, 176there is a risk of it deleting an object that the other process is using 177but hasn't created a reference to. This may just cause the other process 178to fail or may corrupt the repository if the other process later adds a 179reference to the deleted object. Git has two features that significantly 180mitigate this problem: 181 182. Any object with modification time newer than the `--prune` date is kept, 183 along with everything reachable from it. 184 185. Most operations that add an object to the database update the 186 modification time of the object if it is already present so that #1 187 applies. 188 189However, these features fall short of a complete solution, so users who 190run commands concurrently have to live with some risk of corruption (which 191seems to be low in practice) unless they turn off automatic garbage 192collection with 'git config gc.auto 0'. 193 194HOOKS 195----- 196 197The 'git gc --auto' command will run the 'pre-auto-gc' hook. See 198linkgit:githooks[5] for more information. 199 200 201SEE ALSO 202-------- 203linkgit:git-prune[1] 204linkgit:git-reflog[1] 205linkgit:git-repack[1] 206linkgit:git-rerere[1] 207 208GIT 209--- 210Part of the linkgit:git[1] suite