[PATCH v3] archive: describe compression level option

[PATCH v3] archive: describe compression level option

[Bagas Sanjaya]

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(-)

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
 -------------

base-commit: f443b226ca681d87a3a31e245a70e6bc2769123c
-- 
An old man doll... just what I always wanted! - Clara

Re: [PATCH v3] archive: describe compression level option

[Junio C Hamano]

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.