{"thread":{"id":"56718","subject":"[PATCH v2] archive: rewrite description for compression level option","startedAt":"2021-10-15T12:14:36Z","lastAt":"2021-10-16T05:19:47Z","messageCount":4,"participants":["Bagas Sanjaya","Ævar Arnfjörð Bjarmason","Junio C Hamano"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"438838","messageId":"20211015121336.46981-1-bagasdotme@gmail.com","threadId":"56718","inReplyTo":null,"subject":"[PATCH v2] archive: rewrite description for compression level option","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-15T12:13:37Z","receivedAt":"2021-10-15T12:14:36Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Rewrite the description of `-#` option. Since the option is also\nsupported on tar archive, move to OPTIONS section and remove EXTRA.\n\nSigned-off-by: Bagas Sanjaya \n---\n Changes since v1 [1]:\n - Mention common levels (store-only, fastest time, and best\n compression).\n - Note that compression level option is supported by both zip and\n tar format, so move the description to OPTIONS section.\n\n [1]: https://lore.kernel.org/git/xmqqpms6akup.fsf@gitster.g/T/#t\n\n Documentation/git-archive.txt | 24 ++++++++----------------\n 1 file changed, 8 insertions(+), 16 deletions(-)\n\ndiff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\nindex 9f8172828d..9aecc0936c 100644\n--- a/Documentation/git-archive.txt\n+++ b/Documentation/git-archive.txt\n@@ -9,7 +9,7 @@ git-archive - Create an archive of files from a named tree\n SYNOPSIS\n --------\n [verse]\n-'git archive' [--format=] [--list] [--prefix=/] []\n+'git archive' [--format=] [--list] [--prefix=/] [-#]\n \t [-o | --output=] [--worktree-attributes]\n \t [--remote= [--exec=]] \n \t [...]\n@@ -65,10 +65,6 @@ OPTIONS\n \tLook for attributes in .gitattributes files in the working tree\n \tas well (see <>).\n \n-::\n-\tThis can be any options that the archiver backend understands.\n-\tSee next section.\n-\n --remote=::\n \tInstead of making a tar archive from the local repository,\n \tretrieve a tar archive from a remote repository. Note that the\n@@ -88,17 +84,13 @@ OPTIONS\n \tof the current working directory are included in the archive.\n \tIf one or more paths are specified, only these are included.\n \n-BACKEND EXTRA OPTIONS\n----------------------\n-\n-zip\n-~~~\n--0::\n-\tStore the files instead of deflating them.\n--9::\n-\tHighest and slowest compression level. You can specify any\n-\tnumber from 1 to 9 to adjust compression speed and ratio.\n-\n+-#::\n+\tSelect the compression level. The supported levels and default\n+\tvalue (if none is selected) are depending on compression command\n+\tbackend configured for the selected format (either explicitly with\n+\t`--format` or inferred from file name specified with `-o`). Common\n+\tvalues are `-0` for only storing files (zip only), `-1` for fastest\n+\tcompression time, and `-9` for best compression ratio.\n \n CONFIGURATION\n -------------\n\nbase-commit: 2bd2f258f4195ac54293a3f45b86457c0bd5fc11\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"438846","messageId":"87h7die9jj.fsf@evledraar.gmail.com","threadId":"56718","inReplyTo":"20211015121336.46981-1-bagasdotme@gmail.com","subject":"Re: [PATCH v2] archive: rewrite description for compression level option","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-10-15T12:46:29Z","receivedAt":"2021-10-15T12:51:39Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Fri, Oct 15 2021, Bagas Sanjaya wrote:\n\n> Rewrite the description of `-#` option. Since the option is also\n> supported on tar archive, move to OPTIONS section and remove EXTRA.\n>\n> Signed-off-by: Bagas Sanjaya \n> ---\n> Changes since v1 [1]:\n> - Mention common levels (store-only, fastest time, and best\n> compression).\n> - Note that compression level option is supported by both zip and\n> tar format, so move the description to OPTIONS section.\n>\n> [1]: https://lore.kernel.org/git/xmqqpms6akup.fsf@gitster.g/T/#t\n>\n> Documentation/git-archive.txt | 24 ++++++++----------------\n> 1 file changed, 8 insertions(+), 16 deletions(-)\n>\n> diff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\n> index 9f8172828d..9aecc0936c 100644\n> --- a/Documentation/git-archive.txt\n> +++ b/Documentation/git-archive.txt\n> @@ -9,7 +9,7 @@ git-archive - Create an archive of files from a named tree\n> SYNOPSIS\n> --------\n> [verse]\n> -'git archive' [--format=] [--list] [--prefix=/] []\n> +'git archive' [--format=] [--list] [--prefix=/] [-#]\n> \t [-o | --output=] [--worktree-attributes]\n> \t [--remote= [--exec=]] \n> \t [...]\n> @@ -65,10 +65,6 @@ OPTIONS\n> \tLook for attributes in .gitattributes files in the working tree\n> \tas well (see <>).\n> \n> -::\n> -\tThis can be any options that the archiver backend understands.\n> -\tSee next section.\n> -\n> --remote=::\n> \tInstead of making a tar archive from the local repository,\n> \tretrieve a tar archive from a remote repository. Note that the\n> @@ -88,17 +84,13 @@ OPTIONS\n> \tof the current working directory are included in the archive.\n> \tIf one or more paths are specified, only these are included.\n> \n> -BACKEND EXTRA OPTIONS\n> ----------------------\n> -\n> -zip\n> -~~~\n> --0::\n> -\tStore the files instead of deflating them.\n> --9::\n> -\tHighest and slowest compression level. You can specify any\n> -\tnumber from 1 to 9 to adjust compression speed and ratio.\n> -\n> +-#::\n> +\tSelect the compression level. The supported levels and default\n> +\tvalue (if none is selected) are depending on compression command\n> +\tbackend configured for the selected format (either explicitly with\n> +\t`--format` or inferred from file name specified with `-o`). Common\n> +\tvalues are `-0` for only storing files (zip only), `-1` for fastest\n> +\tcompression time, and `-9` for best compression ratio.\n\n\nThis is getting there, but I think we really should not have a -# in the\nsynopsis, since that's not how we refer to a digit-wildcard in any other\ncontext. And users might assume that a literal -# is meant, some\ncommonly used tools even support that, e.g. try:\n\n curl -L -o /dev/null -# https://cdimage.debian.org/debian-cd/current/amd64/iso-dvd/debian-11.1.0-amd64-DVD-1.iso\n\nLet's just use \"[-<0..9 digit>[\", or \"[-]\" in the SYNOPSIS and\nexplain that it's 0..9 below in this section..\n"},{"id":"438876","messageId":"xmqq7dee8c5v.fsf@gitster.g","threadId":"56718","inReplyTo":"87h7die9jj.fsf@evledraar.gmail.com","subject":"Re: [PATCH v2] archive: rewrite description for compression level option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-15T16:50:52Z","receivedAt":"2021-10-15T16:50:58Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason writes:\n\n>> SYNOPSIS\n>> --------\n>> [verse]\n>> -'git archive' [--format=] [--list] [--prefix=/] []\n>> +'git archive' [--format=] [--list] [--prefix=/] [-#]\n>> \t [-o | --output=] [--worktree-attributes]\n>> \t [--remote= [--exec=]] \n>> \t [...]\n>> @@ -65,10 +65,6 @@ OPTIONS\n>> \tLook for attributes in .gitattributes files in the working tree\n>> \tas well (see <>).\n>> \n>> -::\n>> -\tThis can be any options that the archiver backend understands.\n>> -\tSee next section.\n>> -\n>> --remote=::\n>> \tInstead of making a tar archive from the local repository,\n>> \tretrieve a tar archive from a remote repository. Note that the\n>> @@ -88,17 +84,13 @@ OPTIONS\n>> \tof the current working directory are included in the archive.\n>> \tIf one or more paths are specified, only these are included.\n>> \n>> -BACKEND EXTRA OPTIONS\n>> ----------------------\n>> -\n>> -zip\n>> -~~~\n>> --0::\n>> -\tStore the files instead of deflating them.\n>> --9::\n>> -\tHighest and slowest compression level. You can specify any\n>> -\tnumber from 1 to 9 to adjust compression speed and ratio.\n>> -\n>> +-#::\n>> +\tSelect the compression level. The supported levels and default\n>> +\tvalue (if none is selected) are depending on compression command\n>> +\tbackend configured for the selected format (either explicitly with\n>> +\t`--format` or inferred from file name specified with `-o`). Common\n>> +\tvalues are `-0` for only storing files (zip only), `-1` for fastest\n>> +\tcompression time, and `-9` for best compression ratio.\n>\n>\n> This is getting there, but I think we really should not have a -# in the\n> synopsis, since that's not how we refer to a digit-wildcard in any other\n> context. And users might assume that a literal -# is meant, some\n> commonly used tools even support that, e.g. try:\n>\n> curl -L -o /dev/null -# https://cdimage.debian.org/debian-cd/current/amd64/iso-dvd/debian-11.1.0-amd64-DVD-1.iso\n>\n> Let's just use \"[-<0..9 digit>[\", or \"[-]\" in the SYNOPSIS and\n> explain that it's 0..9 below in this section..\n\nI agree with you about `-#`.\n\nI do not think it is a good idea to remove the backend-specific\noption section like this patch does, as the next archiver may not\neven support `-`. Even with the existing two backends, the\ndescription of it need to be different (cf. the other response I\nsent you last night on \"--fast/--best\"?). Rather, the first thing\nto improve would be to _add_ a section for `tar` format, next to the\n`zip` format, I would think, as those who wants to write `tar` do\nnot have to read `zip` specific options, and vice versa.\n\nThe new paragraph on `-#` in the patch may work as a replacement for\nexisting explanation for `zip`-specific extra options, but it needs\nto drop the changes made to make it applicable to any format, like\n\"depending on ... backend\" and \"(zip only)\" if we want to take it.\n\nThanks.\n"},{"id":"438921","messageId":"b28a55da-c74b-8061-108f-10f9df2c0d6f@gmail.com","threadId":"56718","inReplyTo":"xmqq7dee8c5v.fsf@gitster.g","subject":"Re: [PATCH v2] archive: rewrite description for compression level option","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-16T05:19:40Z","receivedAt":"2021-10-16T05:19:47Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"On 15/10/21 23.50, Junio C Hamano wrote:\n> I do not think it is a good idea to remove the backend-specific\n> option section like this patch does, as the next archiver may not\n> even support `-`. Even with the existing two backends, the\n> description of it need to be different (cf. the other response I\n> sent you last night on \"--fast/--best\"?). Rather, the first thing\n> to improve would be to _add_ a section for `tar` format, next to the\n> `zip` format, I would think, as those who wants to write `tar` do\n> not have to read `zip` specific options, and vice versa.\n> \n> The new paragraph on `-#` in the patch may work as a replacement for\n> existing explanation for `zip`-specific extra options, but it needs\n> to drop the changes made to make it applicable to any format, like\n> \"depending on ... backend\" and \"(zip only)\" if we want to take it.\n\nIn current situation, both zip and tar backend supports the compression \nlevel option, so it will end up duplicating description of the option \nfor both backends (with slight differences).\n\n-- \nAn old man doll... just what I always wanted! - Clara\n"}]}