doc: warn people against --max-pack-size

This option is almost never a good idea, as the resulting repository is
larger and slower (see the new explanations in the docs).

I outlined the potential problems. We could go further and make the
option harder to find (or at least, make the command-line option
descriptions a much more terse "you probably don't want this; see
pack.packsizeLimit for details"). But this seems like a minimal change
that may prevent people from thinking it's more useful than it is.

Signed-off-by: Jeff King <peff@peff.net>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

diff --git a/Documentation/config/pack.txt b/Documentation/config/pack.txt
index 3da4ea98e2d4b11d0ff3534efd71ceddb93d9ea8..10c778a9427ddba044ccf7b653ba408d1c238cdc 100644 (file)
--- a/Documentation/config/pack.txt
+++ b/Documentation/config/pack.txt
@@ -99,12 +99,23 @@ pack.packSizeLimit::
        packing to a file when repacking, i.e. the git:// protocol
        is unaffected.  It can be overridden by the `--max-pack-size`
        option of linkgit:git-repack[1].  Reaching this limit results
-       in the creation of multiple packfiles; which in turn prevents
-       bitmaps from being created.
-       The minimum size allowed is limited to 1 MiB.
-       The default is unlimited.
-       Common unit suffixes of 'k', 'm', or 'g' are
-       supported.
+       in the creation of multiple packfiles.
++
+Note that this option is rarely useful, and may result in a larger total
+on-disk size (because Git will not store deltas between packs), as well
+as worse runtime performance (object lookup within multiple packs is
+slower than a single pack, and optimizations like reachability bitmaps
+cannot cope with multiple packs).
++
+If you need to actively run Git using smaller packfiles (e.g., because your
+filesystem does not support large files), this option may help. But if
+your goal is to transmit a packfile over a medium that supports limited
+sizes (e.g., removable media that cannot store the whole repository),
+you are likely better off creating a single large packfile and splitting
+it using a generic multi-volume archive tool (e.g., Unix `split`).
++
+The minimum size allowed is limited to 1 MiB. The default is unlimited.
+Common unit suffixes of 'k', 'm', or 'g' are supported.
 
 pack.useBitmaps::
        When true, git will use pack bitmaps (if available) when packing

diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
index f85cb7ea934cb92f1e6b0be75d1d3984fa0af164..c20b9785109504622e21143446174d5b276d234d 100644 (file)
--- a/Documentation/git-pack-objects.txt
+++ b/Documentation/git-pack-objects.txt
@@ -118,10 +118,10 @@ depth is 4095.
        into multiple independent packfiles, each not larger than the
        given size. The size can be suffixed with
        "k", "m", or "g". The minimum size allowed is limited to 1 MiB.
-       This option
-       prevents the creation of a bitmap index.
        The default is unlimited, unless the config variable
-       `pack.packSizeLimit` is set.
+       `pack.packSizeLimit` is set. Note that this option may result in
+       a larger and slower repository; see the discussion in
+       `pack.packSizeLimit`.
 
 --honor-pack-keep::
        This flag causes an object already in a local pack that

diff --git a/Documentation/git-repack.txt b/Documentation/git-repack.txt
index fbd4b4ae06777f7ee45165c8c5c4d1bf2bbad7d3..7bb797cbe852d4c443081d019047996f7d5d1e80 100644 (file)
--- a/Documentation/git-repack.txt
+++ b/Documentation/git-repack.txt
@@ -121,7 +121,9 @@ depth is 4095.
        If specified, multiple packfiles may be created, which also
        prevents the creation of a bitmap index.
        The default is unlimited, unless the config variable
-       `pack.packSizeLimit` is set.
+       `pack.packSizeLimit` is set. Note that this option may result in
+       a larger and slower repository; see the discussion in
+       `pack.packSizeLimit`.
 
 -b::
 --write-bitmap-index::