Jonathan Tan <jonathantanmy@xxxxxxxxxx> 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@xxxxxxxxxx> > --- > 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.
