{"thread":{"id":"57690","subject":"[PATCH] doc txt & -h consistency: fix recent \"cat-file\" inconsistency","startedAt":"2022-04-07T19:09:15Z","lastAt":"2022-04-08T18:34:00Z","messageCount":4,"participants":["Ævar Arnfjörð Bjarmason","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"453287","messageId":"patch-1.1-79404e05d73-20220407T185645Z-avarab@gmail.com","threadId":"57690","inReplyTo":null,"subject":"[PATCH] doc txt & -h consistency: fix recent \"cat-file\" inconsistency","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-04-07T19:08:59Z","receivedAt":"2022-04-07T19:09:15Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"The cat-file SYNOPSIS and help output were made consistent in\n83dc443439c (cat-file: don't whitespace-pad \"(...)\" in SYNOPSIS and\nusage output, 2022-01-10).\n\nThey then drifted apart again in 440c705ea63 (cat-file: add\n--batch-command mode, 2022-02-18). Let's fix that and list the new\n--batch-command option in the SYNOPSIS section.\n\nSigned-off-by: Ævar Arnfjörð Bjarmason <avarab@gmail.com>\n---\n Documentation/git-cat-file.txt | 2 +-\n 1 file changed, 1 insertion(+), 1 deletion(-)\n\ndiff --git a/Documentation/git-cat-file.txt b/Documentation/git-cat-file.txt\nindex 70c5b4f12d1..24a811f0ef6 100644\n--- a/Documentation/git-cat-file.txt\n+++ b/Documentation/git-cat-file.txt\n@@ -12,7 +12,7 @@ SYNOPSIS\n 'git cat-file' <type> <object>\n 'git cat-file' (-e | -p) <object>\n 'git cat-file' (-t | -s) [--allow-unknown-type] <object>\n-'git cat-file' (--batch | --batch-check) [--batch-all-objects]\n+'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]\n \t     [--buffer] [--follow-symlinks] [--unordered]\n \t     [--textconv | --filters]\n 'git cat-file' (--textconv | --filters)\n-- \n2.36.0.rc0.849.g2d5b5d9ab01\n\n"},{"id":"453288","messageId":"xmqqv8vkr64h.fsf@gitster.g","threadId":"57690","inReplyTo":"patch-1.1-79404e05d73-20220407T185645Z-avarab@gmail.com","subject":"Re: [PATCH] doc txt & -h consistency: fix recent \"cat-file\" inconsistency","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-07T20:27:42Z","receivedAt":"2022-04-07T20:40:02Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n\n> Subject: Re: [PATCH] doc txt & -h consistency: fix recent \"cat-file\" inconsistency\n\nIOW ...\n\n> -'git cat-file' (--batch | --batch-check) [--batch-all-objects]\n> +'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]\n\n... we forgot to add \"--batch-command\" to the documentation, even\nthough we added it to the usage text in the source.\n\nAnd explained that way, this change makes quite a lot of sense.\n\nIt could be a worthwhile longer-term goal to make it consistent\nbetween the synopsis and the usage text\", but we are far away from\nsuch a goal.  I'd rather keep such a topic outside this focused fix.\n\nGiven that we have been pushing to stop listing individual options\nin SYNOPSIS, and instead using <option> placeholder, and also list\ndifferent operation mode of a single command on separate lines,\nbetween\n\n    $ git commit -h 2>&1 | sed -e '/^$/q'\n    $ git commit --help | sed -ne '/^SYNOPSIS/,/^$/p'\n\nwe would want to pick the one we have from the command (i.e. the\nformer) and update the documentation source for the latter.\n\n    Side note: and no, we do not want to tie the documentation to a\n    particular build too tightly, and it is a no-no to generate the\n    documentation source from 'git cmd -h' output.  Even when an\n    option is conditionally excluded from a particular build, I'd\n    like to be able to build and publish documentation for wider\n    audience than just to myself.\n\nSomebody needs to go through the comparison of individual\nsubcommands and present a good plan.  I find that, in comparison\nbetween the -h and --help output, neither is quite satisfactory for\n\"git bisect\", for example.  It would be a huge task and would be a\ndistraction during the pre-release period.\n\nThanks.\n"},{"id":"453322","messageId":"220408.864k34c4wo.gmgdl@evledraar.gmail.com","threadId":"57690","inReplyTo":"xmqqv8vkr64h.fsf@gitster.g","subject":"Re: [PATCH] doc txt & -h consistency: fix recent \"cat-file\" inconsistency","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2022-04-08T08:55:46Z","receivedAt":"2022-04-08T09:18:30Z","isPatch":true,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Thu, Apr 07 2022, Junio C Hamano wrote:\n\n> Ævar Arnfjörð Bjarmason  <avarab@gmail.com> writes:\n>\n>> Subject: Re: [PATCH] doc txt & -h consistency: fix recent \"cat-file\" inconsistency\n>\n> IOW ...\n>\n>> -'git cat-file' (--batch | --batch-check) [--batch-all-objects]\n>> +'git cat-file' (--batch | --batch-check | --batch-command) [--batch-all-objects]\n>\n> ... we forgot to add \"--batch-command\" to the documentation, even\n> though we added it to the usage text in the source.\n>\n> And explained that way, this change makes quite a lot of sense.\n>\n> It could be a worthwhile longer-term goal to make it consistent\n> between the synopsis and the usage text\", but we are far away from\n> such a goal.  I'd rather keep such a topic outside this focused fix.\n\nYes, I just sent this one in because it's usage new in this release,\nthank for merging it.\n\n> Given that we have been pushing to stop listing individual options\n> in SYNOPSIS, and instead using <option> placeholder, and also list\n> different operation mode of a single command on separate lines,\n> between\n>\n>     $ git commit -h 2>&1 | sed -e '/^$/q'\n>     $ git commit --help | sed -ne '/^SYNOPSIS/,/^$/p'\n>\n> we would want to pick the one we have from the command (i.e. the\n> former) and update the documentation source for the latter.\n\nI think both should have the long form, but we don't need to argue that\npoint here.\n\n> Somebody needs to go through the comparison of individual\n> subcommands and present a good plan.  I find that, in comparison\n> between the -h and --help output, neither is quite satisfactory for\n> \"git bisect\", for example.  It would be a huge task and would be a\n> distraction during the pre-release period.\n\nI have a branch locally that fixes a lot more of these, it just uses\n\"sed\" to extract both the -h output and the SYNOPSIS from the .txt,\nnormalizes both sides (e.g. getting rid of ASCIIDOC-markup) and does a\ntest_cmp of the two.\n\nIt finds a lot of issues which are worth fixing, and which I have some\nqueued patches for (but yeah, not during the rc etc.).\n\nA lot have nothing to do with the \"long form or <options>?\" question. But just:\n\n * Basic formatting issues, e.g. using [-v|--version] instead of [-v |\n   --version], or whitespace-padding or whatever.\n\n * Things like referring to <path> in .txt, and <pathspec> in -h, we\n   should pick one and stick to it.\n\n * Cases where we're 100% the same but miss 1-2 options, e.g. this\n   cat-file case, there's plenty more like it, e.g. ls-remote's -h is\n   missing \"[--sort=<key>]\" (but nothing else).\n\n>     Side note: and no, we do not want to tie the documentation to a\n>     particular build too tightly, and it is a no-no to generate the\n>     documentation source from 'git cmd -h' output.  Even when an\n>     option is conditionally excluded from a particular build, I'd\n>     like to be able to build and publish documentation for wider\n>     audience than just to myself.\n\nI don't have changes to do that, but I think the particular concern\nyou're airing here isn't an issue at all.\n\nI.e. whatever other issues we'd enocunter with such auto-generation we\ndo not have *options* that are conditional on compilation, nor do we\nhave commands that we build and don't build the corresponding\ndocumentation for.\n\nOr the other way aroun,d i.e. if we don't build the command, we don't\nbuild the docs, that's what EXCLUDED_PROGRAMS in the Makefile ferried up\nto Documentation/Makefile is doing.\n\nAnyway, I mentioned that as a solution in some past thread, but I think\nit's probably not worth it v.s. just a test scraping and comparing the\ntwo.\n\nIt's not that big of a deal to update both, it's mainly just that we're\nforgetting it now because we have no structural checks in place.\n\nAnd if we did come up with such a script but didn't want building the\ndocs to require a C compiler we could always make it something you run\nas a developer and commit the result, which is pretty much what we do\nnow, just without the benefit of such a script.\n"},{"id":"453345","messageId":"xmqqee27mnl9.fsf@gitster.g","threadId":"57690","inReplyTo":"220408.864k34c4wo.gmgdl@evledraar.gmail.com","subject":"Re: [PATCH] doc txt & -h consistency: fix recent \"cat-file\" inconsistency","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2022-04-08T18:33:54Z","receivedAt":"2022-04-08T18:34:00Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Ævar Arnfjörð Bjarmason <avarab@gmail.com> writes:\n\n> I think both should have the long form, but we don't need to argue that\n> point here.\n\nRight.\n\n>>     Side note: and no, we do not want to tie the documentation to a\n>>     particular build too tightly, and it is a no-no to generate the\n>>     documentation source from 'git cmd -h' output.  Even when an\n>>     option is conditionally excluded from a particular build, I'd\n>>     like to be able to build and publish documentation for wider\n>>     audience than just to myself.\n>\n> I don't have changes to do that, but I think the particular concern\n> you're airing here isn't an issue at all.\n>\n> I.e. whatever other issues we'd enocunter with such auto-generation we\n> do not have *options* that are conditional on compilation, nor do we\n> have commands that we build and don't build the corresponding\n> documentation for.\n\nThe above seems to only scratch the status quo, while I was with\nmaintainer's hat on when I wrote the above, and was considering\nfuture possibilities as well.  I can very much see us accepting a\npatch to make \"git grep -h\" not showing \"-P\" when Git is built\nwithout pcre support, for example.\n\nSaying \"at all\", is a bit too strong with the argument you have, I\nam afraid.\n"}]}