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