Change git-gc documentation to reflect gc.packrefs implementation.
[git/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--------
e9831e83 11'git-gc' [--prune] [--aggressive] [--auto]
30f610b7
SP
12
13DESCRIPTION
14-----------
15Runs a number of housekeeping tasks within the current repository,
16such as compressing file revisions (to reduce disk space and increase
17performance) and removing unreachable objects which may have been
5162e697 18created from prior invocations of linkgit:git-add[1].
30f610b7
SP
19
20Users are encouraged to run this task on a regular basis within
21each repository to maintain good disk space utilization and good
08fbb136
JK
22operating performance. Some git commands may automatically run
23`git-gc`; see the `--auto` flag below for details.
30f610b7 24
e3ff4b24
JH
25OPTIONS
26-------
27
28--prune::
29 Usually `git-gc` packs refs, expires old reflog entries,
30 packs loose objects,
31 and removes old 'rerere' records. Removal
32 of unreferenced loose objects is an unsafe operation
33 while other git operations are in progress, so it is not
34 done by default. Pass this option if you want it, and only
35 when you know nobody else is creating new objects in the
36 repository at the same time (e.g. never use this option
37 in a cron script).
38
0d7566a5
TT
39--aggressive::
40 Usually 'git-gc' runs very quickly while providing good disk
5049012f
TT
41 space utilization and performance. This option will cause
42 git-gc to more aggressively optimize the repository at the expense
0d7566a5 43 of taking much more time. The effects of this optimization are
5049012f 44 persistent, so this option only needs to be used occasionally; every
0d7566a5 45 few hundred changesets or so.
e9831e83
JH
46
47--auto::
d7e56dbc
JK
48 With this option, `git gc` checks whether any housekeeping is
49 required; if not, it exits without performing any work.
50 Some git commands run `git gc --auto` after performing
51 operations that could create many loose objects.
52+
53Housekeeping is required if there are too many loose objects or
54too many packs in the repository. If the number of loose objects
55exceeds the value of the `gc.auto` configuration variable, then
56all loose objects are combined into a single pack using
57`git-repack -d -l`. Setting the value of `gc.auto` to 0
58disables automatic packing of loose objects.
59+
60If the number of packs exceeds the value of `gc.autopacklimit`,
61then existing packs (except those marked with a `.keep` file)
62are consolidated into a single pack by using the `-A` option of
63`git-repack`. Setting `gc.autopacklimit` to 0 disables
64automatic consolidation of packs.
e3ff4b24 65
30f610b7
SP
66Configuration
67-------------
68
69The optional configuration variable 'gc.reflogExpire' can be
70set to indicate how long historical entries within each branch's
71reflog should remain available in this repository. The setting is
72expressed as a length of time, for example '90 days' or '3 months'.
73It defaults to '90 days'.
74
75The optional configuration variable 'gc.reflogExpireUnreachable'
76can be set to indicate how long historical reflog entries which
77are not part of the current branch should remain available in
78this repository. These types of entries are generally created as
79a result of using `git commit \--amend` or `git rebase` and are the
23bfbb81 80commits prior to the amend or rebase occurring. Since these changes
30f610b7
SP
81are not part of the current project most users will want to expire
82them sooner. This option defaults to '30 days'.
83
84The optional configuration variable 'gc.rerereresolved' indicates
85how long records of conflicted merge you resolved earlier are
86kept. This defaults to 60 days.
87
88The optional configuration variable 'gc.rerereunresolved' indicates
89how long records of conflicted merge you have not resolved are
90kept. This defaults to 15 days.
91
c2120e5e 92The optional configuration variable 'gc.packrefs' determines if
fe2128a8
FLR
93`git gc` runs `git-pack-refs`. This can be set to "nobare" to enable
94it within all non-bare repos or it can be set to a boolean value.
95This defaults to true.
30f610b7 96
0d7566a5
TT
97The optional configuration variable 'gc.aggressiveWindow' controls how
98much time is spent optimizing the delta compression of the objects in
99the repository when the --aggressive option is specified. The larger
100the value, the more time is spent optimizing the delta compression. See
5162e697 101the documentation for the --window' option in linkgit:git-repack[1] for
0d7566a5
TT
102more details. This defaults to 10.
103
30f610b7
SP
104See Also
105--------
5162e697
DM
106linkgit:git-prune[1]
107linkgit:git-reflog[1]
108linkgit:git-repack[1]
109linkgit:git-rerere[1]
30f610b7
SP
110
111Author
112------
113Written by Shawn O. Pearce <spearce@spearce.org>
114
115GIT
116---
5162e697 117Part of the linkgit:git[7] suite