gc docs: downplay the usefulness of --aggressive
The existing "gc --aggressive" docs come just short of recommending to users that they run it regularly. I've personally talked to many users who've taken these docs as an advice to use this option, and have, usually it's (mostly) a waste of time. So let's clarify what it really does, and let the user draw their own conclusions. Let's also clarify the "The effects [...] are persistent" to paraphrase a brief version of Jeff King's explanation at [1]. 1. https://public-inbox.org/git/20190318235356.GK29661@sigill.intra.peff.net/ 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
22d4e3bd19bc81b3db6f372d850ad681333a7fb1
1 file changed
+27
-2
Documentation/git-gc.txt
+27
-2
@@ -39,8 +39,7 @@ OPTIONS
39
space utilization and performance. This option will cause
40
'git gc' to more aggressively optimize the repository at the expense
41
of taking much more time. The effects of this optimization are
42
- persistent, so this option only needs to be used occasionally; every
43
- few hundred changesets or so.
42
+ mostly persistent. See the "AGGRESSIVE" section below for details.
43
44
--auto::
45
With this option, 'git gc' checks whether any housekeeping is
@@ -78,6 +77,32 @@ be performed as well.
77
`.keep` files are consolidated into a single pack. When this
78
option is used, `gc.bigPackThreshold` is ignored.
79
80
+AGGRESSIVE
81
+----------
82
+
83
+When the `--aggressive` option is supplied, linkgit:git-repack[1] will
84
+be invoked with the `-f` flag, which in turn will pass
85
+`--no-reuse-delta` to linkgit:git-pack-objects[1]. This will throw
86
+away any existing deltas and re-compute them, at the expense of
87
+spending much more time on the repacking.
88
+
89
+The effects of this are mostly persistent, e.g. when packs and loose
90
+objects are coalesced into one another pack the existing deltas in
91
+that pack might get re-used, but there are also various cases where we
92
+might pick a sub-optimal delta from a newer pack instead.
93
+
94
+Furthermore, 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
97
+using a larger window size we're more likely to find more optimal
98
+deltas.
99
+
100
+It's probably not worth it to use this option on a given repository
101
+without running tailored performance benchmarks on it. It takes a lot
102
+more time, and the resulting space/delta optimization may or may not
103
+be worth it. Not using this at all is the right trade-off for most
104
+users and their repositories.
105
+
106
CONFIGURATION
107
-------------
108