]>
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 |
22d4e3bd | 42 | mostly persistent. See the "AGGRESSIVE" section below for details. |
e9831e83 JH |
43 | |
44 | --auto:: | |
0b444cdb | 45 | With this option, 'git gc' checks whether any housekeeping is |
d7e56dbc | 46 | required; if not, it exits without performing any work. |
d7e56dbc | 47 | + |
b6a8d09f ÆAB |
48 | See the `gc.auto` option in the "CONFIGURATION" section below for how |
49 | this heuristic works. | |
d7e56dbc | 50 | + |
b6a8d09f ÆAB |
51 | Once housekeeping is triggered by exceeding the limits of |
52 | configuration options such as `gc.auto` and `gc.autoPackLimit`, all | |
b586a96a NTND |
53 | other housekeeping tasks (e.g. rerere, working trees, reflog...) will |
54 | be performed as well. | |
55 | ||
e3ff4b24 | 56 | |
e3e24de1 | 57 | --[no-]cruft:: |
5b92477f | 58 | When expiring unreachable objects, pack them separately into a |
e3e24de1 TB |
59 | cruft pack instead of storing them as loose objects. `--cruft` |
60 | is on by default. | |
5b92477f | 61 | |
37dc6d81 TB |
62 | --max-cruft-size=<n>:: |
63 | When packing unreachable objects into a cruft pack, limit the | |
64 | size of new cruft packs to be at most `<n>` bytes. Overrides any | |
65 | value specified via the `gc.maxCruftSize` configuration. See | |
66 | the `--max-cruft-size` option of linkgit:git-repack[1] for | |
67 | more. | |
68 | ||
58e9d9d4 JS |
69 | --prune=<date>:: |
70 | Prune loose objects older than date (default is 2 weeks ago, | |
61929404 | 71 | overridable by the config variable `gc.pruneExpire`). |
716a5af8 | 72 | --prune=now prunes loose objects regardless of their age and |
f1350d0c MM |
73 | increases the risk of corruption if another process is writing to |
74 | the repository concurrently; see "NOTES" below. --prune is on by | |
75 | default. | |
58e9d9d4 JS |
76 | |
77 | --no-prune:: | |
78 | Do not prune any loose objects. | |
79 | ||
a0c14cbb FL |
80 | --quiet:: |
81 | Suppress all progress reports. | |
82 | ||
64a99eb4 NTND |
83 | --force:: |
84 | Force `git gc` to run even if there may be another `git gc` | |
85 | instance running on this repository. | |
86 | ||
ae4e89e5 | 87 | --keep-largest-pack:: |
05b9013b TB |
88 | All packs except the largest non-cruft pack, any packs marked |
89 | with a `.keep` file, and any cruft pack(s) are consolidated into | |
90 | a single pack. When this option is used, `gc.bigPackThreshold` | |
91 | is ignored. | |
ae4e89e5 | 92 | |
22d4e3bd ÆAB |
93 | AGGRESSIVE |
94 | ---------- | |
95 | ||
96 | When the `--aggressive` option is supplied, linkgit:git-repack[1] will | |
97 | be invoked with the `-f` flag, which in turn will pass | |
98 | `--no-reuse-delta` to linkgit:git-pack-objects[1]. This will throw | |
99 | away any existing deltas and re-compute them, at the expense of | |
100 | spending much more time on the repacking. | |
101 | ||
102 | The effects of this are mostly persistent, e.g. when packs and loose | |
103 | objects are coalesced into one another pack the existing deltas in | |
104 | that pack might get re-used, but there are also various cases where we | |
105 | might pick a sub-optimal delta from a newer pack instead. | |
106 | ||
107 | Furthermore, supplying `--aggressive` will tweak the `--depth` and | |
108 | `--window` options passed to linkgit:git-repack[1]. See the | |
109 | `gc.aggressiveDepth` and `gc.aggressiveWindow` settings below. By | |
110 | using a larger window size we're more likely to find more optimal | |
111 | deltas. | |
112 | ||
113 | It's probably not worth it to use this option on a given repository | |
114 | without running tailored performance benchmarks on it. It takes a lot | |
115 | more time, and the resulting space/delta optimization may or may not | |
116 | be worth it. Not using this at all is the right trade-off for most | |
117 | users and their repositories. | |
118 | ||
76a8788c | 119 | CONFIGURATION |
30f610b7 SP |
120 | ------------- |
121 | ||
18d89fe2 | 122 | include::includes/cmd-config-section-all.txt[] |
b586a96a | 123 | |
b6a8d09f | 124 | include::config/gc.txt[] |
3ffb58be | 125 | |
76a8788c | 126 | NOTES |
3ffb58be JK |
127 | ----- |
128 | ||
f1350d0c | 129 | 'git gc' tries very hard not to delete objects that are referenced |
9df53c5d EN |
130 | anywhere in your repository. In particular, it will keep not only |
131 | objects referenced by your current set of branches and tags, but also | |
fa9ab027 MZ |
132 | objects referenced by the index, remote-tracking branches, reflogs |
133 | (which may reference commits in branches that were later amended or | |
134 | rewound), and anything else in the refs/* namespace. Note that a note | |
135 | (of the kind created by 'git notes') attached to an object does not | |
136 | contribute in keeping the object alive. If you are expecting some | |
137 | objects to be deleted and they aren't, check all of those locations | |
138 | and decide whether it makes sense in your case to remove those | |
139 | references. | |
3ffb58be | 140 | |
f1350d0c MM |
141 | On the other hand, when 'git gc' runs concurrently with another process, |
142 | there is a risk of it deleting an object that the other process is using | |
143 | but hasn't created a reference to. This may just cause the other process | |
144 | to fail or may corrupt the repository if the other process later adds a | |
145 | reference to the deleted object. Git has two features that significantly | |
146 | mitigate this problem: | |
147 | ||
148 | . Any object with modification time newer than the `--prune` date is kept, | |
149 | along with everything reachable from it. | |
150 | ||
151 | . Most operations that add an object to the database update the | |
152 | modification time of the object if it is already present so that #1 | |
153 | applies. | |
154 | ||
155 | However, these features fall short of a complete solution, so users who | |
156 | run commands concurrently have to live with some risk of corruption (which | |
0044f770 | 157 | seems to be low in practice). |
f1350d0c | 158 | |
66bd8ab8 CP |
159 | HOOKS |
160 | ----- | |
161 | ||
162 | The 'git gc --auto' command will run the 'pre-auto-gc' hook. See | |
163 | linkgit:githooks[5] for more information. | |
164 | ||
165 | ||
56ae8df5 | 166 | SEE ALSO |
30f610b7 | 167 | -------- |
5162e697 DM |
168 | linkgit:git-prune[1] |
169 | linkgit:git-reflog[1] | |
170 | linkgit:git-repack[1] | |
171 | linkgit:git-rerere[1] | |
30f610b7 | 172 | |
30f610b7 SP |
173 | GIT |
174 | --- | |
9e1f0a85 | 175 | Part of the linkgit:git[1] suite |