| Message ID | 20211018123822.541406-1-bagasdotme@gmail.com (mailing list archive) |
|---|---|
| State | Superseded |
| Headers | show |
| Series | [v3] archive: describe compression level option | expand |
Bagas Sanjaya <bagasdotme@gmail.com> writes: > Describe the only extra option in `git archive`, that is the compression > level option. Previously this option is only described for zip backend; > add description also for tar backend. Almost there. I think saying just a short "-<number>" would be more appropriate. Both descriptions are clear that they are talking about a number given by the user, and their purpose is to describe what the number means. I do not see much point in using such a long label, which makes the leading '-' less stand out. For an added bonus, use -<digit> for zip, and use -<number> for tar. > zip > ~~~ > +-<compression level number>:: > + Specify compression level. Higher values enables better ratio at > + the expense of longer time. Supported values are from `-0` > + (store-only) to `-9` (best ratio). Default is `-6` if isn't > + specified. I wondered how Info-zip describes what -9 is and how they say phrase it is quite interesting. Regulate the speed of compression using the specified digit #, where -0 indicates no compression (store all files), -1 indicates the fastest compression speed (less compression) and -9 indicates the slowest compression speed (optimal compression, ignores the suffix list). The default compression level is -6. Notice that they do not make much promise on the resulting size; they only talk about speed. At the slowest speed, the tool is allowed to spend more time to explore smaller size, but it may not always be successful, I guess, to achieve the "best compression", so it is a very defensive documentation, but I doubt if it is helful to its readers. Compared to that I think the proposed "best ratio" much more clearly conveys the intention (i.e. "we aim for smaller size")---it would probably be even better to say "smaller size", as there may be many "ratios" in the world and it is not immediately obvious that we are talking about resulting size being small if we do not say so (also "smaller" or "smallest" is more explicit than "best"---the readers don't have to think which between smaller and larger is better). > +tar > +~~~ > +-<compression level number>:: > + Specify compression level. The value will be passed to the > + compression command configured in `tar.<format>.command`. See > + manual page of the configured command for the list of supported > + levels and the default level if this option isn't specified. OK. Thanks.
diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt index 9f8172828d..ca3356d543 100644 --- a/Documentation/git-archive.txt +++ b/Documentation/git-archive.txt @@ -93,12 +93,19 @@ BACKEND EXTRA OPTIONS zip ~~~ --0:: - Store the files instead of deflating them. --9:: - Highest and slowest compression level. You can specify any - number from 1 to 9 to adjust compression speed and ratio. +-<compression level number>:: + Specify compression level. Higher values enables better ratio at + the expense of longer time. Supported values are from `-0` + (store-only) to `-9` (best ratio). Default is `-6` if isn't + specified. +tar +~~~ +-<compression level number>:: + Specify compression level. The value will be passed to the + compression command configured in `tar.<format>.command`. See + manual page of the configured command for the list of supported + levels and the default level if this option isn't specified. CONFIGURATION -------------
Describe the only extra option in `git archive`, that is the compression level option. Previously this option is only described for zip backend; add description also for tar backend. Signed-off-by: Bagas Sanjaya <bagasdotme@gmail.com> --- Changes since v3 [1]: - add description for tar backend - rewrite for zip [1]: https://lore.kernel.org/git/b28a55da-c74b-8061-108f-10f9df2c0d6f@gmail.com/T/#t Documentation/git-archive.txt | 17 ++++++++++++----- 1 file changed, 12 insertions(+), 5 deletions(-) base-commit: f443b226ca681d87a3a31e245a70e6bc2769123c