]> git.ipfire.org Git - thirdparty/git.git/blame - Documentation/git-gc.txt
Merge branch 'js/t3404-typofix' into maint
[thirdparty/git.git] / Documentation / git-gc.txt
CommitLineData
30f610b7
SP
1git-gc(1)
2=========
3
4NAME
5----
6git-gc - Cleanup unnecessary files and optimize the local repository
7
8
9SYNOPSIS
10--------
7791a1d9 11[verse]
ae4e89e5 12'git gc' [--aggressive] [--auto] [--quiet] [--prune=<date> | --no-prune] [--force] [--keep-largest-pack]
30f610b7
SP
13
14DESCRIPTION
15-----------
16Runs a number of housekeeping tasks within the current repository,
17such as compressing file revisions (to reduce disk space and increase
b586a96a
NTND
18performance), removing unreachable objects which may have been
19created from prior invocations of 'git add', packing refs, pruning
c7e8ce6d
ÆAB
20reflog, rerere metadata or stale working trees. May also update ancillary
21indexes such as the commit-graph.
30f610b7 22
b11e8560
ÆAB
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.
30f610b7 33
e3ff4b24
JH
34OPTIONS
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
48See the `gc.auto` option in the "CONFIGURATION" section below for how
49this heuristic works.
d7e56dbc 50+
b6a8d09f
ÆAB
51Once housekeeping is triggered by exceeding the limits of
52configuration options such as `gc.auto` and `gc.autoPackLimit`, all
b586a96a
NTND
53other housekeeping tasks (e.g. rerere, working trees, reflog...) will
54be performed as well.
55
e3ff4b24 56
58e9d9d4
JS
57--prune=<date>::
58 Prune loose objects older than date (default is 2 weeks ago,
61929404 59 overridable by the config variable `gc.pruneExpire`).
716a5af8 60 --prune=now prunes loose objects regardless of their age and
f1350d0c
MM
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.
58e9d9d4
JS
64
65--no-prune::
66 Do not prune any loose objects.
67
a0c14cbb
FL
68--quiet::
69 Suppress all progress reports.
70
64a99eb4
NTND
71--force::
72 Force `git gc` to run even if there may be another `git gc`
73 instance running on this repository.
74
ae4e89e5
NTND
75--keep-largest-pack::
76 All packs except the largest pack and those marked with a
55dfe13d
NTND
77 `.keep` files are consolidated into a single pack. When this
78 option is used, `gc.bigPackThreshold` is ignored.
ae4e89e5 79
22d4e3bd
ÆAB
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
76a8788c 106CONFIGURATION
30f610b7
SP
107-------------
108
b6a8d09f
ÆAB
109The below documentation is the same as what's found in
110linkgit:git-config[1]:
b586a96a 111
b6a8d09f 112include::config/gc.txt[]
3ffb58be 113
76a8788c 114NOTES
3ffb58be
JK
115-----
116
f1350d0c
MM
117'git gc' tries very hard not to delete objects that are referenced
118anywhere in your repository. In
3ffb58be 119particular, it will keep not only objects referenced by your current set
60109d0e
MM
120of branches and tags, but also objects referenced by the index,
121remote-tracking branches, refs saved by 'git filter-branch' in
daecbf22
ÆAB
122refs/original/, reflogs (which may reference commits in branches
123that were later amended or rewound), and anything else in the refs/* namespace.
f1350d0c 124If you are expecting some objects to be deleted and they aren't, check
3ffb58be
JK
125all of those locations and decide whether it makes sense in your case to
126remove those references.
127
f1350d0c
MM
128On the other hand, when 'git gc' runs concurrently with another process,
129there is a risk of it deleting an object that the other process is using
130but hasn't created a reference to. This may just cause the other process
131to fail or may corrupt the repository if the other process later adds a
132reference to the deleted object. Git has two features that significantly
133mitigate this problem:
134
135. Any object with modification time newer than the `--prune` date is kept,
136 along with everything reachable from it.
137
138. Most operations that add an object to the database update the
139 modification time of the object if it is already present so that #1
140 applies.
141
142However, these features fall short of a complete solution, so users who
143run commands concurrently have to live with some risk of corruption (which
0044f770 144seems to be low in practice).
f1350d0c 145
66bd8ab8
CP
146HOOKS
147-----
148
149The 'git gc --auto' command will run the 'pre-auto-gc' hook. See
150linkgit:githooks[5] for more information.
151
152
56ae8df5 153SEE ALSO
30f610b7 154--------
5162e697
DM
155linkgit:git-prune[1]
156linkgit:git-reflog[1]
157linkgit:git-repack[1]
158linkgit:git-rerere[1]
30f610b7 159
30f610b7
SP
160GIT
161---
9e1f0a85 162Part of the linkgit:git[1] suite