gc docs: modernize the advice for manually running "gc"
The docs have been recommending that users need to run this manually, but that hasn't been needed in practice for a long time except in exceptional circumstances. Let's instead have this reflect reality and say that most users don't need to run this manually at all, while briefly describing the sorts sort of cases where "gc" does need to be run manually. Since we're recommending that users run this most of the and usually don't need to tweak it, let's tone down the very prominent example of the gc.auto=0 command. It's sufficient to point to the gc.auto documentation below. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com> Signed-off-by: Junio C Hamano <gitster@pobox.com>
Ævar Arnfjörð Bjarmason committed
Mar 22, 2019 at 10:32 UTC
b11e8560cc1be17268136504cb80b00fbf4182dc
1 file changed
+10
-11
Documentation/git-gc.txt
+10
-11
@@ -20,17 +20,16 @@ created from prior invocations of 'git add', packing refs, pruning
20
reflog, rerere metadata or stale working trees. May also update ancillary
21
indexes such as the commit-graph.
22
23
-Users are encouraged to run this task on a regular basis within
24
-each repository to maintain good disk space utilization and good
25
-operating performance.
26
-
27
-Some git commands may automatically run 'git gc'; see the `--auto` flag
28
-below for details. If you know what you're doing and all you want is to
29
-disable this behavior permanently without further considerations, just do:
30
-
31
-----------------------
32
-$ git config --global gc.auto 0
33
-----------------------
23
+When common porcelain operations that create objects are run, they
24
+will check whether the repository has grown substantially since the
25
+last maintenance, and if so run `git gc` automatically. See `gc.auto`
26
+below for how to disable this behavior.
27
+
28
+Running `git gc` manually should only be needed when adding objects to
29
+a repository without regularly running such porcelain commands, to do
30
+a one-off repository optimization, or e.g. to clean up a suboptimal
31
+mass-import. See the "PACKFILE OPTIMIZATION" section in
32
+linkgit:git-fast-import[1] for more details on the import case.
33
34
OPTIONS
35
-------