Re: [PATCH] Doc: clarify that pack-objects makes packs, plural

[Jeff King <peff@peff.net>]

On Tue, Aug 22, 2017 at 12:56:25PM -0700, Junio C Hamano wrote:

>  - There should be an update to say max-pack-size is not something
>    normal users would ever want.

Agreed.

> diff --git a/Documentation/git-pack-objects.txt b/Documentation/git-pack-objects.txt
> index 8973510a41..3aa6234501 100644
> --- a/Documentation/git-pack-objects.txt
> +++ b/Documentation/git-pack-objects.txt
> @@ -108,9 +108,13 @@ base-name::
>  	is taken from the `pack.windowMemory` configuration variable.
>  
>  --max-pack-size=<n>::
> -	Maximum size of each output pack file. The size can be suffixed with
> +	In unusual scenarios, you may not be able to create files
> +	larger than certain size on your filesystem, and this option
> +	can be used to tell the command to split the output packfile
> +	into multiple independent packfiles and what the maximum
> +	size of each packfile is. The size can be suffixed with
>  	"k", "m", or "g". The minimum size allowed is limited to 1 MiB.
> -	If specified, multiple packfiles may be created, which also
> +	This option
>  	prevents the creation of a bitmap index.
>  	The default is unlimited, unless the config variable
>  	`pack.packSizeLimit` is set.

I wonder if it is worth mentioning the other downside: that the sum of
the split packfiles may be substantially larger than a single packfile
would be (due to lost delta opportunities between the split packs).

For the sneaker-net case, you are much better off generating a single
pack and then using "split" and "cat" to reconstruct it on the other end
Not that I think we should go into such detail in the manpage, but I
have to wonder if --max-pack-size has outlived its usefulness. The only
use case I can think of is a filesystem that cannot hold files larger
than N bytes.

-Peff