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

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

Eric Sunshine <sunshine@sunshineco.com> writes:

>> +-<digit>::
>> +       Regulate compression level using the specified <digit>. Higher
>> +       values enables smaller size at the expense of slower time.
>
> s/enables/enable/
>
> A couple notes:
>
> "slower time" is an unusual way to convey the concept; perhaps say it
> takes "more time".
>
> I think it was mentioned earlier in this thread that higher
> compression level does not necessarily mean better compression, though
> that is certainly the intent; it only means that the tool will "try
> harder" to make the result smaller. Perhaps it's worth using more
> exact phrasing (or perhaps it doesn't matter and that's getting too
> much into the weeds).
>
>> +       Supported values are from `-0` (store-only) to `-9` (best ratio).
>> +       Default is `-6` if isn't specified.
>
> s/if isn't/if it isn't/
> ...or...
> s/if isn't/if not/

Sounds all sensible.

In summary, perhaps something like this?  I still have "-9 (best
ratio)" which does not say it is merely the intent and not
guarantee, but the resulting text read a bit funny with "best ratio"
replaced with "try hardest".

----- >8 --------- >8 --------- >8 --------- >8 --------- >8 -----
From: Bagas Sanjaya <bagasdotme@gmail.com>
Date: Fri, 22 Oct 2021 13:45:44 +0700
Subject: [PATCH] archive: describe compression level option

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>
Helped-by: Eric Sunshine <sunshine@sunshineco.com>
Signed-off-by: Junio C Hamano <gitster@pobox.com>
---
$ git range-diff --word-diff @{1}...
1:  c27c11dc35 ! 1:  63e8b48637 archive: describe compression level option
    @@ Metadata
     ## Commit message ##
        archive: describe compression level option
    
        Describe the only [-extra-]{+<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.
    
    @@ Documentation/git-archive.txt: BACKEND EXTRA OPTIONS
    -	Highest and slowest compression level.  You can specify any
    -	number from 1 to 9 to adjust compression speed and ratio.
    +-<digit>::
    +	[-Regulate-]{+Specify+} compression [-level using the specified <digit>. Higher-]
    [-+-]{+level.  Larger+} values [-enables smaller size at-]{+allows+} the [-expense of slower time.-]{+command+}
    +	{+to spend more time to compress to smaller size.+}  Supported
{+++}	values are from `-0` (store-only) to `-9` (best ratio).
    +	Default is `-6` if [-isn't specified.-]{+not given.+}
     
    +tar
    +~~~

 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..fea2e84fdf 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.
+-<digit>::
+	Specify compression level.  Larger values allows the command
+	to spend more time to compress to smaller size.  Supported
+	values are from `-0` (store-only) to `-9` (best ratio).
+	Default is `-6` if not given.
 
+tar
+~~~
+-<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
 -------------
-- 
2.33.1-943-g0f03e78e89