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

[Junio C Hamano <gitster@pobox.com>]

Jonathan Tan <jonathantanmy@google.com> writes:

> The documentation for pack-objects describes that it creates "a packed
> archive of objects", which is confusing because it may create multiple
> packs if --max-pack-size is set. Update the documentation to clarify
> this.
>
> Signed-off-by: Jonathan Tan <jonathantanmy@google.com>
> ---
> It took me quite some time before I realized that pack-objects actually
> may write multiple packs, the opening lines of the doc confusing me.
> Here's a doc update.
> ---

I have a mixed feeling about this one.  

Yes, the command _can_ be told to split a packfile into multiple
with an option, but the actual benefit of doing so is rather
dubious.  On boxes with smaller address space, I thought windowed
mmap access into large packfiles work just fine.  I also think the
motivation behind the "max-size" thing was to split into smaller
pieces so that sneaker-netting on multiple CD-ROMs becomes easier or
something (silly) like that---there should be a more suitable tool
that is not specific to Git for such usecase, I would imagine.

So I am OK with "and writes either one or more" in the description,
but I'd prefer to see that "--max-pack-size" thing gets described as
an aberration, not a norm.

IOW,

 - I think the "NAME" part that gives a single line summary of what
   the command is about can and should stay as before.  A single
   archive is the norm, and we do not particularly recommend people
   to think it is a good idea to produce multiple packfiles.

 - The change in this patch for description part, which should give
   a fairly complete view of what it can do, is good.

 - The change for 'base-name' documentation that stresses that
   .pack/.idx come in pairs and share the same <SHA-1> is good.

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

For the last one, perhaps something like this:


 Documentation/git-pack-objects.txt | 8 ++++++--
 1 file changed, 6 insertions(+), 2 deletions(-)

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.