[PATCH 4/4] gc docs: downplay the usefulness of --aggressive

["Ævar Arnfjörð Bjarmason" <avarab@gmail.com>]

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@gmail.com>
---
 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