{"thread":{"id":"56729","subject":"[PATCH v3] archive: describe compression level option","startedAt":"2021-10-18T12:38:55Z","lastAt":"2021-10-18T17:00:56Z","messageCount":2,"participants":["Bagas Sanjaya","Junio C Hamano"],"isPatch":true,"patchVersion":3,"patchTotal":null},"messages":[{"id":"438981","messageId":"20211018123822.541406-1-bagasdotme@gmail.com","threadId":"56729","inReplyTo":null,"subject":"[PATCH v3] archive: describe compression level option","fromName":"Bagas Sanjaya","fromEmail":"bagasdotme@gmail.com","sentAt":"2021-10-18T12:38:22Z","receivedAt":"2021-10-18T12:38:55Z","isPatch":true,"sender":{"key":"bagasdotme@gmail.com","avatar":"https://avatars.githubusercontent.com/u/40219486?v=4"},"body":"Describe the only extra option in `git archive`, that is the compression\nlevel option. Previously this option is only described for zip backend;\nadd description also for tar backend.\n\nSigned-off-by: Bagas Sanjaya \n---\n Changes since v3 [1]:\n - add description for tar backend\n - rewrite for zip\n\n [1]:\nhttps://lore.kernel.org/git/b28a55da-c74b-8061-108f-10f9df2c0d6f@gmail.com/T/#t\n\n Documentation/git-archive.txt | 17 ++++++++++++-----\n 1 file changed, 12 insertions(+), 5 deletions(-)\n\ndiff --git a/Documentation/git-archive.txt b/Documentation/git-archive.txt\nindex 9f8172828d..ca3356d543 100644\n--- a/Documentation/git-archive.txt\n+++ b/Documentation/git-archive.txt\n@@ -93,12 +93,19 @@ BACKEND EXTRA OPTIONS\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+\tSpecify compression level. Higher values enables better ratio at\n+\tthe expense of longer time. Supported values are from `-0`\n+\t(store-only) to `-9` (best ratio). Default is `-6` if isn't\n+\tspecified.\n \n+tar\n+~~~\n+-::\n+\tSpecify compression level. The value will be passed to the\n+\tcompression command configured in `tar..command`. See\n+\tmanual page of the configured command for the list of supported\n+\tlevels and the default level if this option isn't specified.\n \n CONFIGURATION\n -------------\n\nbase-commit: f443b226ca681d87a3a31e245a70e6bc2769123c\n-- \nAn old man doll... just what I always wanted! - Clara\n\n"},{"id":"438988","messageId":"xmqq8ryqxo72.fsf@gitster.g","threadId":"56729","inReplyTo":"20211018123822.541406-1-bagasdotme@gmail.com","subject":"Re: [PATCH v3] archive: describe compression level option","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-10-18T17:00:49Z","receivedAt":"2021-10-18T17:00:56Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Bagas Sanjaya writes:\n\n> Describe the only extra option in `git archive`, that is the compression\n> level option. Previously this option is only described for zip backend;\n> add description also for tar backend.\n\nAlmost there. \n\nI think saying just a short \"-\" would be more appropriate.\nBoth descriptions are clear that they are talking about a number\ngiven by the user, and their purpose is to describe what the number\nmeans. I do not see much point in using such a long label, which\nmakes the leading '-' less stand out.\n\nFor an added bonus, use - for zip, and use - for tar.\n\n> zip\n> ~~~\n> +-::\n> +\tSpecify compression level. Higher values enables better ratio at\n> +\tthe expense of longer time. Supported values are from `-0`\n> +\t(store-only) to `-9` (best ratio). Default is `-6` if isn't\n> +\tspecified.\n\nI wondered how Info-zip describes what -9 is and how they say phrase\nit is quite interesting.\n\n Regulate the speed of compression using the specified digit #,\n where -0 indicates no compression (store all files), -1\n indicates the fastest compression speed (less compression) and\n -9 indicates the slowest compression speed (optimal compression,\n ignores the suffix list). The default compression level is -6.\n\nNotice that they do not make much promise on the resulting size;\nthey only talk about speed. At the slowest speed, the tool is\nallowed to spend more time to explore smaller size, but it may not\nalways be successful, I guess, to achieve the \"best compression\", so\nit is a very defensive documentation, but I doubt if it is helful to\nits readers. Compared to that I think the proposed \"best ratio\"\nmuch more clearly conveys the intention (i.e. \"we aim for smaller\nsize\")---it would probably be even better to say \"smaller size\", as\nthere may be many \"ratios\" in the world and it is not immediately\nobvious that we are talking about resulting size being small if we\ndo not say so (also \"smaller\" or \"smallest\" is more explicit than\n\"best\"---the readers don't have to think which between smaller and\nlarger is better).\n\n> +tar\n> +~~~\n> +-::\n> +\tSpecify compression level. The value will be passed to the\n> +\tcompression command configured in `tar..command`. See\n> +\tmanual page of the configured command for the list of supported\n> +\tlevels and the default level if this option isn't specified.\n\nOK.\n\nThanks.\n"}]}