gc docs: include the "gc.*" section from "config" in "gc"
Rather than duplicating the documentation for the various "gc" options let's include the "gc" docs from git-config. They were mostly better already, and now we don't have the same docs in two places with subtly different wording. In the cases where the git-gc(1) docs were saying something the "gc" docs in git-config(1) didn't cover move the relevant section over to the git-config(1) docs. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Apr 7, 2019 at 21:52 UTC
b6a8d09f6d85693dad19bbcfd2b18f9e6fc81ee4
2 files changed
+35
-80
Documentation/config/gc.txt
+28
-1
@@ -2,24 +2,39 @@ gc.aggressiveDepth::
2
The depth parameter used in the delta compression
3
algorithm used by 'git gc --aggressive'. This defaults
4
to 50.
5
++
6
+See the documentation for the `--depth` option in
7
+linkgit:git-repack[1] for more details.
8
9
gc.aggressiveWindow::
10
The window size parameter used in the delta compression
11
algorithm used by 'git gc --aggressive'. This defaults
12
to 250.
13
++
14
+See the documentation for the `--window` option in
15
+linkgit:git-repack[1] for more details.
16
17
gc.auto::
18
When there are approximately more than this many loose
19
objects in the repository, `git gc --auto` will pack them.
20
Some Porcelain commands use this command to perform a
21
light-weight garbage collection from time to time. The
16
- default value is 6700. Setting this to 0 disables it.
22
+ default value is 6700.
23
++
24
+Setting this to 0 disables not only automatic packing based on the
25
+number of loose objects, but any other heuristic `git gc --auto` will
26
+otherwise use to determine if there's work to do, such as
27
+`gc.autoPackLimit`.
28
29
gc.autoPackLimit::
30
When there are more than this many packs that are not
31
marked with `*.keep` file in the repository, `git gc
32
--auto` consolidates them into one larger pack. The
33
default value is 50. Setting this to 0 disables it.
34
+ Setting `gc.auto` to 0 will also disable this.
35
++
36
+See the `gc.bigPackThreshold` configuration variable below. When in
37
+use, it'll affect how the auto pack limit works.
38
39
gc.autoDetach::
40
Make `git gc --auto` return immediately and run in background
@@ -36,6 +51,11 @@ Note that if the number of kept packs is more than gc.autoPackLimit,
51
this configuration variable is ignored, all packs except the base pack
52
will be repacked. After this the number of packs should go below
53
gc.autoPackLimit and gc.bigPackThreshold should be respected again.
54
++
55
+If the amount of memory estimated for `git repack` to run smoothly is
56
+not available and `gc.bigPackThreshold` is not set, the largest
57
+pack will also be excluded (this is the equivalent of running `git gc`
58
+with `--keep-base-pack`).
59
60
gc.writeCommitGraph::
61
If true, then gc will rewrite the commit-graph file when
@@ -94,6 +114,13 @@ gc.<pattern>.reflogExpireUnreachable::
114
With "<pattern>" (e.g. "refs/stash")
115
in the middle, the setting applies only to the refs that
116
match the <pattern>.
117
++
118
+These types of entries are generally created as
119
+a result of using `git commit --amend` or `git rebase` and are the
120
+commits prior to the amend or rebase occurring. Since these changes
121
+are not part of the current project most users will want to expire
122
+them sooner, which is why the default is more aggressive than
123
+`gc.reflogExpire`.
124
125
gc.rerereResolved::
126
Records of conflicted merge you resolved earlier are
Documentation/git-gc.txt
+7
-79
@@ -45,28 +45,12 @@ OPTIONS
45
--auto::
46
With this option, 'git gc' checks whether any housekeeping is
47
required; if not, it exits without performing any work.
48
- Some git commands run `git gc --auto` after performing
49
- operations that could create many loose objects. Housekeeping
50
- is required if there are too many loose objects or too many
51
- packs in the repository.
48
+
53
-If the number of loose objects exceeds the value of the `gc.auto`
54
-configuration variable, then all loose objects are combined into a
55
-single pack. Setting the value of `gc.auto`
56
-to 0 disables automatic packing of loose objects.
49
+See the `gc.auto` option in the "CONFIGURATION" section below for how
50
+this heuristic works.
51
+
58
-If the number of packs exceeds the value of `gc.autoPackLimit`,
59
-then existing packs (except those marked with a `.keep` file
60
-or over `gc.bigPackThreshold` limit)
61
-are consolidated into a single pack.
62
-If the amount of memory estimated for `git repack` to run smoothly is
63
-not available and `gc.bigPackThreshold` is not set, the largest
64
-pack will also be excluded (this is the equivalent of running `git gc`
65
-with `--keep-base-pack`).
66
-Setting `gc.autoPackLimit` to 0 disables automatic consolidation of
67
-packs.
68
-+
69
-If houskeeping is required due to many loose objects or packs, all
52
+Once housekeeping is triggered by exceeding the limits of
53
+configuration options such as `gc.auto` and `gc.autoPackLimit`, all
54
other housekeeping tasks (e.g. rerere, working trees, reflog...) will
55
be performed as well.
56
@@ -97,66 +81,10 @@ be performed as well.
81
CONFIGURATION
82
-------------
83
100
-The optional configuration variable `gc.reflogExpire` can be
101
-set to indicate how long historical entries within each branch's
102
-reflog should remain available in this repository. The setting is
103
-expressed as a length of time, for example '90 days' or '3 months'.
104
-It defaults to '90 days'.
105
-
106
-The optional configuration variable `gc.reflogExpireUnreachable`
107
-can be set to indicate how long historical reflog entries which
108
-are not part of the current branch should remain available in
109
-this repository. These types of entries are generally created as
110
-a result of using `git commit --amend` or `git rebase` and are the
111
-commits prior to the amend or rebase occurring. Since these changes
112
-are not part of the current project most users will want to expire
113
-them sooner. This option defaults to '30 days'.
114
-
115
-The above two configuration variables can be given to a pattern. For
116
-example, this sets non-default expiry values only to remote-tracking
117
-branches:
118
-
119
-------------
120
-[gc "refs/remotes/*"]
121
- reflogExpire = never
122
- reflogExpireUnreachable = 3 days
123
-------------
124
-
125
-The optional configuration variable `gc.rerereResolved` indicates
126
-how long records of conflicted merge you resolved earlier are
127
-kept. This defaults to 60 days.
128
-
129
-The optional configuration variable `gc.rerereUnresolved` indicates
130
-how long records of conflicted merge you have not resolved are
131
-kept. This defaults to 15 days.
132
-
133
-The optional configuration variable `gc.packRefs` determines if
134
-'git gc' runs 'git pack-refs'. This can be set to "notbare" to enable
135
-it within all non-bare repos or it can be set to a boolean value.
136
-This defaults to true.
137
-
138
-The optional configuration variable `gc.writeCommitGraph` determines if
139
-'git gc' should run 'git commit-graph write'. This can be set to a
140
-boolean value. This defaults to false.
141
-
142
-The optional configuration variable `gc.aggressiveWindow` controls how
143
-much time is spent optimizing the delta compression of the objects in
144
-the repository when the --aggressive option is specified. The larger
145
-the value, the more time is spent optimizing the delta compression. See
146
-the documentation for the --window option in linkgit:git-repack[1] for
147
-more details. This defaults to 250.
148
-
149
-Similarly, the optional configuration variable `gc.aggressiveDepth`
150
-controls --depth option in linkgit:git-repack[1]. This defaults to 50.
151
-
152
-The optional configuration variable `gc.pruneExpire` controls how old
153
-the unreferenced loose objects have to be before they are pruned. The
154
-default is "2 weeks ago".
155
-
156
-Optional configuration variable `gc.worktreePruneExpire` controls how
157
-old a stale working tree should be before `git worktree prune` deletes
158
-it. Default is "3 months ago".
84
+The below documentation is the same as what's found in
85
+linkgit:git-config[1]:
86
87
+include::config/gc.txt[]
88
89
NOTES
90
-----