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

From: Eric Sunshine <sunshine@sunshineco.com>
Date: Oct 22, 2021, 06:57 UTC
Message-ID: <CAPig+cRAi4ZR+_+Dh+DoUBkG=sgWTekxadob2YvThJQhr9tqfA@mail.gmail.com>
In-Reply-To: <20211022064543.28950-1-bagasdotme@gmail.com>

On Fri, Oct 22, 2021 at 2:48 AM Bagas Sanjaya <bagasdotme@gmail.com> wrote:

Show 13 quoted lines

> 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>
> ---
> diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt
> @@ -93,12 +93,19 @@ BACKEND EXTRA OPTIONS
>  zip
>  ~~~
> +-<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/

Show 7 quoted lines

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