* [PATCH v4] archive: describe compression level option
@ 2021-10-22 6:45 Bagas Sanjaya
2021-10-22 6:57 ` Eric Sunshine
0 siblings, 1 reply; 6+ messages in thread
From: Bagas Sanjaya @ 2021-10-22 6:45 UTC (permalink / raw)
To: git
Cc: vagabon.xyz, Junio C Hamano,
Ævar Arnfjörð Bjarmason, René Scharfe,
Jeff King, 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]:
- use smaller size - slower time term
- use <digit> and <number> for compression level
[1]: https://lore.kernel.org/git/xmqq8ryqxo72.fsf@gitster.g/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..ecfae7e268 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>::
+ Regulate compression level using the specified <digit>. Higher
+ values enables smaller size at the expense of slower time.
+ Supported values are from `-0` (store-only) to `-9` (best ratio).
+ Default is `-6` if isn't specified.
+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
-------------
base-commit: f443b226ca681d87a3a31e245a70e6bc2769123c
--
An old man doll... just what I always wanted! - Clara
^ permalink raw reply related [flat|nested] 6+ messages in thread* Re: [PATCH v4] archive: describe compression level option
2021-10-22 6:45 [PATCH v4] archive: describe compression level option Bagas Sanjaya
@ 2021-10-22 6:57 ` Eric Sunshine
2021-10-23 21:13 ` Junio C Hamano
0 siblings, 1 reply; 6+ messages in thread
From: Eric Sunshine @ 2021-10-22 6:57 UTC (permalink / raw)
To: Bagas Sanjaya
Cc: Git List, vagabon.xyz, Junio C Hamano,
Ævar Arnfjörð Bjarmason, René Scharfe,
Jeff King
On Fri, Oct 22, 2021 at 2:48 AM Bagas Sanjaya <bagasdotme@gmail.com> wrote:
> 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/
> +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.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v4] archive: describe compression level option
2021-10-22 6:57 ` Eric Sunshine
@ 2021-10-23 21:13 ` Junio C Hamano
2021-10-25 16:39 ` Eric Sunshine
0 siblings, 1 reply; 6+ messages in thread
From: Junio C Hamano @ 2021-10-23 21:13 UTC (permalink / raw)
To: Eric Sunshine
Cc: Bagas Sanjaya, Git List, vagabon.xyz,
Ævar Arnfjörð Bjarmason, René Scharfe,
Jeff King
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
^ permalink raw reply related [flat|nested] 6+ messages in thread* Re: [PATCH v4] archive: describe compression level option
2021-10-23 21:13 ` Junio C Hamano
@ 2021-10-25 16:39 ` Eric Sunshine
2021-10-25 17:48 ` Junio C Hamano
0 siblings, 1 reply; 6+ messages in thread
From: Eric Sunshine @ 2021-10-25 16:39 UTC (permalink / raw)
To: Junio C Hamano
Cc: Bagas Sanjaya, Git List, vagabon.xyz,
Ævar Arnfjörð Bjarmason, René Scharfe,
Jeff King
On Sat, Oct 23, 2021 at 5:13 PM Junio C Hamano <gitster@pobox.com> wrote:
> 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".
> > [...]
> >> + 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".
This version looks fine. Thanks.
^ permalink raw reply [flat|nested] 6+ messages in thread
* Re: [PATCH v4] archive: describe compression level option
2021-10-25 16:39 ` Eric Sunshine
@ 2021-10-25 17:48 ` Junio C Hamano
2021-10-25 17:57 ` Eric Sunshine
0 siblings, 1 reply; 6+ messages in thread
From: Junio C Hamano @ 2021-10-25 17:48 UTC (permalink / raw)
To: Eric Sunshine
Cc: Bagas Sanjaya, Git List, vagabon.xyz,
Ævar Arnfjörð Bjarmason, René Scharfe,
Jeff King
Eric Sunshine <sunshine@sunshineco.com> writes:
>> 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".
>
> This version looks fine. Thanks.
Thanks for proofreading. I have locally fixed a grammo ("Larger
values allow the command"), by the way.
^ permalink raw reply [flat|nested] 6+ messages in thread* Re: [PATCH v4] archive: describe compression level option
2021-10-25 17:48 ` Junio C Hamano
@ 2021-10-25 17:57 ` Eric Sunshine
0 siblings, 0 replies; 6+ messages in thread
From: Eric Sunshine @ 2021-10-25 17:57 UTC (permalink / raw)
To: Junio C Hamano
Cc: Bagas Sanjaya, Git List, vagabon.xyz,
Ævar Arnfjörð Bjarmason, René Scharfe,
Jeff King
On Mon, Oct 25, 2021 at 1:49 PM Junio C Hamano <gitster@pobox.com> wrote:
> Eric Sunshine <sunshine@sunshineco.com> writes:
> >> 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".
> >
> > This version looks fine. Thanks.
>
> Thanks for proofreading. I have locally fixed a grammo ("Larger
> values allow the command"), by the way.
Bleh. My eyes slid right over that grammo. Oh well.
With that grammo fix, it looks even better.
^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2021-10-25 17:58 UTC | newest]
Thread overview: 6+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
2021-10-22 6:45 [PATCH v4] archive: describe compression level option Bagas Sanjaya
2021-10-22 6:57 ` Eric Sunshine
2021-10-23 21:13 ` Junio C Hamano
2021-10-25 16:39 ` Eric Sunshine
2021-10-25 17:48 ` Junio C Hamano
2021-10-25 17:57 ` Eric Sunshine
Code repositories for project(s) associated with this public inbox
https://80x24.org/mirrors/git.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).