Jonathan Tan <[email protected]> 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 <[email protected]>
> ---
> 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.
