1GIT-GC(1) Git Manual GIT-GC(1)
2
6 git-gc - Cleanup unnecessary files and optimize the local repository
7
9 git gc [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack]
10
13 Runs a number of housekeeping tasks within the current repository, such
14 as compressing file revisions (to reduce disk space and increase
15 performance), removing unreachable objects which may have been created
16 from prior invocations of git add, packing refs, pruning reflog, rerere
17 metadata or stale working trees. May also update ancillary indexes such
18 as the commit-graph.
19 When common porcelain operations that create objects are run, they will
21 check whether the repository has grown substantially since the last
22 maintenance, and if so run git gc automatically. See gc.auto below for
23 how to disable this behavior.
24 Running git gc manually should only be needed when adding objects to a
26 repository without regularly running such porcelain commands, to do a
27 one-off repository optimization, or e.g. to clean up a suboptimal
28 mass-import. See the "PACKFILE OPTIMIZATION" section in git-fast-
29 import(1) for more details on the import case.
30
32 --aggressive
33 Usually git gc runs very quickly while providing good disk space
34 utilization and performance. This option will cause git gc to more
35 aggressively optimize the repository at the expense of taking much
36 more time. The effects of this optimization are mostly persistent.
37 See the "AGGRESSIVE" section below for details.
38 --auto
40 With this option, git gc checks whether any housekeeping is
41 required; if not, it exits without performing any work.
42 See the gc.auto option in the "CONFIGURATION" section below for how
44 this heuristic works.
45 Once housekeeping is triggered by exceeding the limits of
47 configuration options such as gc.auto and gc.autoPackLimit, all
48 other housekeeping tasks (e.g. rerere, working trees, reflog...)
49 will be performed as well.
50 --prune=<date>
52 Prune loose objects older than date (default is 2 weeks ago,
53 overridable by the config variable gc.pruneExpire). --prune=now
54 prunes loose objects regardless of their age and increases the risk
55 of corruption if another process is writing to the repository
56 concurrently; see "NOTES" below. --prune is on by default.
57 --no-prune
59 Do not prune any loose objects.
60 --quiet
62 Suppress all progress reports.
63 --force
65 Force git gc to run even if there may be another git gc instance
66 running on this repository.
67 --keep-largest-pack
69 All packs except the largest pack and those marked with a .keep
70 files are consolidated into a single pack. When this option is
71 used, gc.bigPackThreshold is ignored.
72
74 When the --aggressive option is supplied, git-repack(1) will be invoked
75 with the -f flag, which in turn will pass --no-reuse-delta to git-pack-
76 objects(1). This will throw away any existing deltas and re-compute
77 them, at the expense of spending much more time on the repacking.
78 The effects of this are mostly persistent, e.g. when packs and loose
80 objects are coalesced into one another pack the existing deltas in that
81 pack might get re-used, but there are also various cases where we might
82 pick a sub-optimal delta from a newer pack instead.
83 Furthermore, supplying --aggressive will tweak the --depth and --window
85 options passed to git-repack(1). See the gc.aggressiveDepth and
86 gc.aggressiveWindow settings below. By using a larger window size we’re
87 more likely to find more optimal deltas.
88 It’s probably not worth it to use this option on a given repository
90 without running tailored performance benchmarks on it. It takes a lot
91 more time, and the resulting space/delta optimization may or may not be
92 worth it. Not using this at all is the right trade-off for most users
93 and their repositories.
94
96 The below documentation is the same as what’s found in git-config(1):
97 gc.aggressiveDepth
99 The depth parameter used in the delta compression algorithm used by
100 git gc --aggressive. This defaults to 50, which is the default for
101 the --depth option when --aggressive isn’t in use.
102 See the documentation for the --depth option in git-repack(1) for
104 more details.
105 gc.aggressiveWindow
107 The window size parameter used in the delta compression algorithm
108 used by git gc --aggressive. This defaults to 250, which is a much
109 more aggressive window size than the default --window of 10.
110 See the documentation for the --window option in git-repack(1) for
112 more details.
113 gc.auto
115 When there are approximately more than this many loose objects in
116 the repository, git gc --auto will pack them. Some Porcelain
117 commands use this command to perform a light-weight garbage
118 collection from time to time. The default value is 6700.
119 Setting this to 0 disables not only automatic packing based on the
121 number of loose objects, but any other heuristic git gc --auto will
122 otherwise use to determine if there’s work to do, such as
123 gc.autoPackLimit.
124 gc.autoPackLimit
126 When there are more than this many packs that are not marked with
127 *.keep file in the repository, git gc --auto consolidates them into
128 one larger pack. The default value is 50. Setting this to 0
129 disables it. Setting gc.auto to 0 will also disable this.
130 See the gc.bigPackThreshold configuration variable below. When in
132 use, it’ll affect how the auto pack limit works.
133 gc.autoDetach
135 Make git gc --auto return immediately and run in background if the
136 system supports it. Default is true.
137 gc.bigPackThreshold
139 If non-zero, all packs larger than this limit are kept when git gc
140 is run. This is very similar to --keep-base-pack except that all
141 packs that meet the threshold are kept, not just the base pack.
142 Defaults to zero. Common unit suffixes of k, m, or g are supported.
143 Note that if the number of kept packs is more than
145 gc.autoPackLimit, this configuration variable is ignored, all packs
146 except the base pack will be repacked. After this the number of
147 packs should go below gc.autoPackLimit and gc.bigPackThreshold
148 should be respected again.
149 If the amount of memory estimated for git repack to run smoothly is
151 not available and gc.bigPackThreshold is not set, the largest pack
152 will also be excluded (this is the equivalent of running git gc
153 with --keep-base-pack).
154 gc.writeCommitGraph
156 If true, then gc will rewrite the commit-graph file when git-gc(1)
157 is run. When using git gc --auto the commit-graph will be updated
158 if housekeeping is required. Default is true. See git-commit-
159 graph(1) for details.
160 gc.logExpiry
162 If the file gc.log exists, then git gc --auto will print its
163 content and exit with status zero instead of running unless that
164 file is more than gc.logExpiry old. Default is "1.day". See
165 gc.pruneExpire for more ways to specify its value.
166 gc.packRefs
168 Running git pack-refs in a repository renders it unclonable by Git
169 versions prior to 1.5.1.2 over dumb transports such as HTTP. This
170 variable determines whether git gc runs git pack-refs. This can be
171 set to notbare to enable it within all non-bare repos or it can be
172 set to a boolean value. The default is true.
173 gc.pruneExpire
175 When git gc is run, it will call prune --expire 2.weeks.ago.
176 Override the grace period with this config variable. The value
177 "now" may be used to disable this grace period and always prune
178 unreachable objects immediately, or "never" may be used to suppress
179 pruning. This feature helps prevent corruption when git gc runs
180 concurrently with another process writing to the repository; see
181 the "NOTES" section of git-gc(1).
182 gc.worktreePruneExpire
184 When git gc is run, it calls git worktree prune --expire
185 3.months.ago. This config variable can be used to set a different
186 grace period. The value "now" may be used to disable the grace
187 period and prune $GIT_DIR/worktrees immediately, or "never" may be
188 used to suppress pruning.
189 gc.reflogExpire, gc.<pattern>.reflogExpire
191 git reflog expire removes reflog entries older than this time;
192 defaults to 90 days. The value "now" expires all entries
193 immediately, and "never" suppresses expiration altogether. With
194 "<pattern>" (e.g. "refs/stash") in the middle the setting applies
195 only to the refs that match the <pattern>.
196 gc.reflogExpireUnreachable, gc.<pattern>.reflogExpireUnreachable
198 git reflog expire removes reflog entries older than this time and
199 are not reachable from the current tip; defaults to 30 days. The
200 value "now" expires all entries immediately, and "never" suppresses
201 expiration altogether. With "<pattern>" (e.g. "refs/stash") in the
202 middle, the setting applies only to the refs that match the
203 <pattern>.
204 These types of entries are generally created as a result of using
206 git commit --amend or git rebase and are the commits prior to the
207 amend or rebase occurring. Since these changes are not part of the
208 current project most users will want to expire them sooner, which
209 is why the default is more aggressive than gc.reflogExpire.
210 gc.rerereResolved
212 Records of conflicted merge you resolved earlier are kept for this
213 many days when git rerere gc is run. You can also use more
214 human-readable "1.month.ago", etc. The default is 60 days. See git-
215 rerere(1).
216 gc.rerereUnresolved
218 Records of conflicted merge you have not resolved are kept for this
219 many days when git rerere gc is run. You can also use more
220 human-readable "1.month.ago", etc. The default is 15 days. See git-
221 rerere(1).
222
224 git gc tries very hard not to delete objects that are referenced
225 anywhere in your repository. In particular, it will keep not only
226 objects referenced by your current set of branches and tags, but also
227 objects referenced by the index, remote-tracking branches, notes saved
228 by git notes under refs/notes/, reflogs (which may reference commits in
229 branches that were later amended or rewound), and anything else in the
230 refs/* namespace. If you are expecting some objects to be deleted and
231 they aren’t, check all of those locations and decide whether it makes
232 sense in your case to remove those references.
233 On the other hand, when git gc runs concurrently with another process,
235 there is a risk of it deleting an object that the other process is
236 using but hasn’t created a reference to. This may just cause the other
237 process to fail or may corrupt the repository if the other process
238 later adds a reference to the deleted object. Git has two features that
239 significantly mitigate this problem:
240 1. Any object with modification time newer than the --prune date is
242 kept, along with everything reachable from it.
243 2. Most operations that add an object to the database update the
245 modification time of the object if it is already present so that #1
246 applies.
247 However, these features fall short of a complete solution, so users who
249 run commands concurrently have to live with some risk of corruption
250 (which seems to be low in practice).
251
253 The git gc --auto command will run the pre-auto-gc hook. See
254 githooks(5) for more information.
255
257 git-prune(1) git-reflog(1) git-repack(1) git-rerere(1)
258
260 Part of the git(1) suite
261Git 2.24.1 12/10/2019 GIT-GC(1)