Eric Sunshine <sunshine@xxxxxxxxxxxxxx> 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@xxxxxxxxx>
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@xxxxxxxxx>
Helped-by: Eric Sunshine <sunshine@xxxxxxxxxxxxxx>
Signed-off-by: Junio C Hamano <gitster@xxxxxxxxx>
---
$ 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
