]>
Commit | Line | Data |
---|---|---|
30f610b7 SP |
1 | git-gc(1) |
2 | ========= | |
3 | ||
4 | NAME | |
5 | ---- | |
6 | git-gc - Cleanup unnecessary files and optimize the local repository | |
7 | ||
8 | ||
9 | SYNOPSIS | |
10 | -------- | |
7791a1d9 | 11 | [verse] |
ae4e89e5 | 12 | 'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack] |
30f610b7 SP |
13 | |
14 | DESCRIPTION | |
15 | ----------- | |
16 | Runs a number of housekeeping tasks within the current repository, | |
17 | such as compressing file revisions (to reduce disk space and increase | |
b586a96a NTND |
18 | performance), removing unreachable objects which may have been |
19 | created from prior invocations of 'git add', packing refs, pruning | |
c7e8ce6d ÆAB |
20 | reflog, rerere metadata or stale working trees. May also update ancillary |
21 | indexes such as the commit-graph. | |
30f610b7 | 22 | |
b11e8560 ÆAB |
23 | When common porcelain operations that create objects are run, they |
24 | will check whether the repository has grown substantially since the | |
25 | last maintenance, and if so run `git gc` automatically. See `gc.auto` | |
26 | below for how to disable this behavior. | |
27 | ||
28 | Running `git gc` manually should only be needed when adding objects to | |
29 | a repository without regularly running such porcelain commands, to do | |
30 | a one-off repository optimization, or e.g. to clean up a suboptimal | |
31 | mass-import. See the "PACKFILE OPTIMIZATION" section in | |
32 | linkgit:git-fast-import[1] for more details on the import case. | |
30f610b7 | 33 | |
e3ff4b24 JH |
34 | OPTIONS |
35 | ------- | |
36 | ||
0d7566a5 | 37 | --aggressive:: |
0b444cdb | 38 | Usually 'git gc' runs very quickly while providing good disk |
5049012f | 39 | space utilization and performance. This option will cause |
0b444cdb | 40 | 'git gc' to more aggressively optimize the repository at the expense |
0d7566a5 | 41 | of taking much more time. The effects of this optimization are |
5049012f | 42 | persistent, so this option only needs to be used occasionally; every |
0d7566a5 | 43 | few hundred changesets or so. |
e9831e83 JH |
44 | |
45 | --auto:: | |
0b444cdb | 46 | With this option, 'git gc' checks whether any housekeeping is |
d7e56dbc JK |
47 | required; if not, it exits without performing any work. |
48 | Some git commands run `git gc --auto` after performing | |
b586a96a NTND |
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. | |
d7e56dbc | 52 | + |
b586a96a NTND |
53 | If the number of loose objects exceeds the value of the `gc.auto` |
54 | configuration variable, then all loose objects are combined into a | |
cf9cd771 | 55 | single pack. Setting the value of `gc.auto` |
b586a96a | 56 | to 0 disables automatic packing of loose objects. |
d7e56dbc | 57 | + |
da0005b8 | 58 | If the number of packs exceeds the value of `gc.autoPackLimit`, |
55dfe13d NTND |
59 | then existing packs (except those marked with a `.keep` file |
60 | or over `gc.bigPackThreshold` limit) | |
cf9cd771 | 61 | are consolidated into a single pack. |
9806f5a7 NTND |
62 | If the amount of memory is estimated not enough for `git repack` to |
63 | run smoothly and `gc.bigPackThreshold` is not set, the largest | |
64 | pack will also be excluded (this is the equivalent of running `git gc` | |
65 | with `--keep-base-pack`). | |
66 | Setting `gc.autoPackLimit` to 0 disables automatic consolidation of | |
67 | packs. | |
b586a96a NTND |
68 | + |
69 | If houskeeping is required due to many loose objects or packs, all | |
70 | other housekeeping tasks (e.g. rerere, working trees, reflog...) will | |
71 | be performed as well. | |
72 | ||
e3ff4b24 | 73 | |
58e9d9d4 JS |
74 | --prune=<date>:: |
75 | Prune loose objects older than date (default is 2 weeks ago, | |
61929404 | 76 | overridable by the config variable `gc.pruneExpire`). |
716a5af8 | 77 | --prune=now prunes loose objects regardless of their age and |
f1350d0c MM |
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. | |
58e9d9d4 JS |
81 | |
82 | --no-prune:: | |
83 | Do not prune any loose objects. | |
84 | ||
a0c14cbb FL |
85 | --quiet:: |
86 | Suppress all progress reports. | |
87 | ||
64a99eb4 NTND |
88 | --force:: |
89 | Force `git gc` to run even if there may be another `git gc` | |
90 | instance running on this repository. | |
91 | ||
ae4e89e5 NTND |
92 | --keep-largest-pack:: |
93 | All packs except the largest pack and those marked with a | |
55dfe13d NTND |
94 | `.keep` files are consolidated into a single pack. When this |
95 | option is used, `gc.bigPackThreshold` is ignored. | |
ae4e89e5 | 96 | |
76a8788c | 97 | CONFIGURATION |
30f610b7 SP |
98 | ------------- |
99 | ||
ae9f6311 | 100 | The optional configuration variable `gc.reflogExpire` can be |
30f610b7 SP |
101 | set to indicate how long historical entries within each branch's |
102 | reflog should remain available in this repository. The setting is | |
103 | expressed as a length of time, for example '90 days' or '3 months'. | |
104 | It defaults to '90 days'. | |
105 | ||
ae9f6311 | 106 | The optional configuration variable `gc.reflogExpireUnreachable` |
30f610b7 SP |
107 | can be set to indicate how long historical reflog entries which |
108 | are not part of the current branch should remain available in | |
109 | this repository. These types of entries are generally created as | |
6cf378f0 | 110 | a result of using `git commit --amend` or `git rebase` and are the |
23bfbb81 | 111 | commits prior to the amend or rebase occurring. Since these changes |
30f610b7 SP |
112 | are not part of the current project most users will want to expire |
113 | them sooner. This option defaults to '30 days'. | |
114 | ||
eb523a8d | 115 | The above two configuration variables can be given to a pattern. For |
60109d0e | 116 | example, this sets non-default expiry values only to remote-tracking |
eb523a8d JH |
117 | branches: |
118 | ||
119 | ------------ | |
120 | [gc "refs/remotes/*"] | |
121 | reflogExpire = never | |
da0005b8 | 122 | reflogExpireUnreachable = 3 days |
eb523a8d JH |
123 | ------------ |
124 | ||
ae9f6311 | 125 | The optional configuration variable `gc.rerereResolved` indicates |
30f610b7 SP |
126 | how long records of conflicted merge you resolved earlier are |
127 | kept. This defaults to 60 days. | |
128 | ||
ae9f6311 | 129 | The optional configuration variable `gc.rerereUnresolved` indicates |
30f610b7 SP |
130 | how long records of conflicted merge you have not resolved are |
131 | kept. This defaults to 15 days. | |
132 | ||
ae9f6311 | 133 | The optional configuration variable `gc.packRefs` determines if |
4be0c352 | 134 | 'git gc' runs 'git pack-refs'. This can be set to "notbare" to enable |
fe2128a8 FLR |
135 | it within all non-bare repos or it can be set to a boolean value. |
136 | This defaults to true. | |
30f610b7 | 137 | |
b8b4cb27 | 138 | The optional configuration variable `gc.writeCommitGraph` determines if |
d5d5d7b6 DS |
139 | 'git gc' should run 'git commit-graph write'. This can be set to a |
140 | boolean value. This defaults to false. | |
141 | ||
ae9f6311 | 142 | The optional configuration variable `gc.aggressiveWindow` controls how |
0d7566a5 TT |
143 | much time is spent optimizing the delta compression of the objects in |
144 | the repository when the --aggressive option is specified. The larger | |
145 | the value, the more time is spent optimizing the delta compression. See | |
bed21a8a | 146 | the documentation for the --window option in linkgit:git-repack[1] for |
c9486ae8 | 147 | more details. This defaults to 250. |
125f8146 | 148 | |
ae9f6311 | 149 | Similarly, the optional configuration variable `gc.aggressiveDepth` |
7e823880 | 150 | controls --depth option in linkgit:git-repack[1]. This defaults to 50. |
0d7566a5 | 151 | |
ae9f6311 | 152 | The optional configuration variable `gc.pruneExpire` controls how old |
25ee9731 JS |
153 | the unreferenced loose objects have to be before they are pruned. The |
154 | default is "2 weeks ago". | |
155 | ||
b586a96a NTND |
156 | Optional configuration variable `gc.worktreePruneExpire` controls how |
157 | old a stale working tree should be before `git worktree prune` deletes | |
158 | it. Default is "3 months ago". | |
159 | ||
3ffb58be | 160 | |
76a8788c | 161 | NOTES |
3ffb58be JK |
162 | ----- |
163 | ||
f1350d0c MM |
164 | 'git gc' tries very hard not to delete objects that are referenced |
165 | anywhere in your repository. In | |
3ffb58be | 166 | particular, it will keep not only objects referenced by your current set |
60109d0e MM |
167 | of branches and tags, but also objects referenced by the index, |
168 | remote-tracking branches, refs saved by 'git filter-branch' in | |
3ed0b11e | 169 | refs/original/, or reflogs (which may reference commits in branches |
3ffb58be | 170 | that were later amended or rewound). |
f1350d0c | 171 | If you are expecting some objects to be deleted and they aren't, check |
3ffb58be JK |
172 | all of those locations and decide whether it makes sense in your case to |
173 | remove those references. | |
174 | ||
f1350d0c MM |
175 | On the other hand, when 'git gc' runs concurrently with another process, |
176 | there is a risk of it deleting an object that the other process is using | |
177 | but hasn't created a reference to. This may just cause the other process | |
178 | to fail or may corrupt the repository if the other process later adds a | |
179 | reference to the deleted object. Git has two features that significantly | |
180 | mitigate 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 | ||
189 | However, these features fall short of a complete solution, so users who | |
190 | run commands concurrently have to live with some risk of corruption (which | |
191 | seems to be low in practice) unless they turn off automatic garbage | |
192 | collection with 'git config gc.auto 0'. | |
193 | ||
66bd8ab8 CP |
194 | HOOKS |
195 | ----- | |
196 | ||
197 | The 'git gc --auto' command will run the 'pre-auto-gc' hook. See | |
198 | linkgit:githooks[5] for more information. | |
199 | ||
200 | ||
56ae8df5 | 201 | SEE ALSO |
30f610b7 | 202 | -------- |
5162e697 DM |
203 | linkgit:git-prune[1] |
204 | linkgit:git-reflog[1] | |
205 | linkgit:git-repack[1] | |
206 | linkgit:git-rerere[1] | |
30f610b7 | 207 | |
30f610b7 SP |
208 | GIT |
209 | --- | |
9e1f0a85 | 210 | Part of the linkgit:git[1] suite |