The existing "gc --aggressive" docs come just short of recommending to users that they run it regularly. In reality it's a waste of CPU for most users, and may even make things actively worse. I've personally talked to many users who've taken these docs as an advice to use this option, and have. Let's change this documentation to better reflect reality, i.e. for most users using --aggressive is a waste of time, and may even be actively making things worse. Let's also clarify the "The effects [...] are persistent" to clearly note that that's true to the extent that subsequent gc's aren't going to re-roll existing packs generated with --aggressive into a new set of packs. Signed-off-by: Ævar Arnfjörð Bjarmason <avarab@xxxxxxxxx> --- Documentation/git-gc.txt | 18 ++++++++++++++---- 1 file changed, 14 insertions(+), 4 deletions(-) diff --git a/Documentation/git-gc.txt b/Documentation/git-gc.txt index 154c7c5e652..d0eaba98db5 100644 --- a/Documentation/git-gc.txt +++ b/Documentation/git-gc.txt @@ -41,10 +41,20 @@ OPTIONS --aggressive:: Usually 'git gc' runs very quickly while providing good disk space utilization and performance. This option will cause - 'git gc' to more aggressively optimize the repository at the expense - of taking much more time. The effects of this optimization are - persistent, so this option only needs to be used occasionally; every - few hundred changesets or so. + 'git gc' to more aggressively optimize the repository to save storage space + at the expense of taking much more time. ++ +Using this option may optimize for disk space at the expense of +runtime performance. See the `--depth` and `--window` documentation in +linkgit:git-repack[1]. It is not recommended that this option be used +to improve performance for a given repository without running tailored +performance benchmarks on it. It may make things better, or worse. Not +using this at all is the right trade-off for most users and their +repositories. ++ +The effects of this option are persistent to the extent that +`gc.autoPackLimit` and friends don't cause a consolidation of existing +pack(s) generated with this option. --auto:: With this option, 'git gc' checks whether any housekeeping is -- 2.21.0.360.g471c308f928
