{"thread":{"id":"57116","subject":"Custom subcommand help handlers","startedAt":"2021-12-18T16:08:59Z","lastAt":"2022-02-12T22:38:16Z","messageCount":20,"participants":["Sean Allred","Ævar Arnfjörð Bjarmason","Erik Cervin Edin","Johannes Schindelin","brian m. carlson","Junio C Hamano","Philip Oakley"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"444425","messageId":"CABceR4ZW4rRWZnH0ZBkWty_H84Z4CmXque_LO+1edETEWrO8PQ@mail.gmail.com","threadId":"57116","inReplyTo":null,"subject":"Custom subcommand help handlers","fromName":"Sean Allred","fromEmail":"allred.sean@gmail.com","sentAt":"2021-12-18T16:08:45Z","receivedAt":"2021-12-18T16:08:59Z","isPatch":false,"sender":{"key":"allred.sean@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2082195?v=4"},"body":"Hi folks,\n\nI've got a custom subcommand I'm distributing in my company to\nintegrate with our bug-tracker. It's a pretty robust utility and has\nits own help function, but running `git foo --help` doesn't pass\n--help to my git-foo utility. I asked a question[1] about this\nscenario on the Windows fork and they directed me upstream.\n\nIt sounds like `git foo --help` is internally consumed as `git help\nfoo`, which forwards requests to info/man/web handlers per config.\nBeing on Windows and knowing my peers as I do, the vast majority of my\nusers won't be familiar with info or man. The HTML documentation used\nby the web handler is in a Git4Win-controlled installation directory\nthat I'd really rather not touch/maintain. I really just want `git foo\n--help` to call `git-foo --help`.\n\nWhat's the best way to go about this?\n\nIn the event the best next step is to start a patch, does it sound\nreasonable to simply not perform this `git foo --help` -> `git help\nfoo` transformation for non-builtins? Or, while I don't relish the\nidea, would some kind of config option be needed?\n\nBest,\nSean Allred\n\n[1]: https://github.com/git-for-windows/git/discussions/3553\n"},{"id":"444450","messageId":"211220.86k0fzwmq2.gmgdl@evledraar.gmail.com","threadId":"57116","inReplyTo":"CABceR4ZW4rRWZnH0ZBkWty_H84Z4CmXque_LO+1edETEWrO8PQ@mail.gmail.com","subject":"Re: Custom subcommand help handlers","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-12-20T11:11:16Z","receivedAt":"2021-12-20T11:16:10Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Sat, Dec 18 2021, Sean Allred wrote:\n\n> Hi folks,\n>\n> I've got a custom subcommand I'm distributing in my company to\n> integrate with our bug-tracker. It's a pretty robust utility and has\n> its own help function, but running `git foo --help` doesn't pass\n> --help to my git-foo utility. I asked a question[1] about this\n> scenario on the Windows fork and they directed me upstream.\n>\n> It sounds like `git foo --help` is internally consumed as `git help\n> foo`, which forwards requests to info/man/web handlers per config.\n> Being on Windows and knowing my peers as I do, the vast majority of my\n> users won't be familiar with info or man. The HTML documentation used\n> by the web handler is in a Git4Win-controlled installation directory\n> that I'd really rather not touch/maintain. I really just want `git foo\n> --help` to call `git-foo --help`.\n>\n> What's the best way to go about this?\n>\n> In the event the best next step is to start a patch, does it sound\n> reasonable to simply not perform this `git foo --help` -> `git help\n> foo` transformation for non-builtins? Or, while I don't relish the\n> idea, would some kind of config option be needed?\n>\n> Best,\n> Sean Allred\n>\n> [1]: https://github.com/git-for-windows/git/discussions/3553\n\nI don't know if there's a solution that'll please everyone here, but\nit's definitely not narrowing this to built-ins. E.g. \"git send-email\n--help\" will expect to show the manual, so will \"git annex --help\".\n"},{"id":"444455","messageId":"CA+JQ7M8oxzUAkw-Nv4X+3bJt7cBhsUaqFKd67Y=LNLnv2kgM+Q@mail.gmail.com","threadId":"57116","inReplyTo":"211220.86k0fzwmq2.gmgdl@evledraar.gmail.com","subject":"Re: Custom subcommand help handlers","fromName":"Erik Cervin Edin","fromEmail":"erik@cervined.in","sentAt":"2021-12-20T12:37:26Z","receivedAt":"2021-12-20T12:38:03Z","isPatch":false,"sender":{"key":"erik@cervined.in","avatar":null},"body":"It looks like any git cmd --help is transformed into\n\"git help --exclude-guides cmd\"\nThis is used to differentiate \"git cmd --help\" and \"git help cmd\".\n\nIt's used with aliases to print the alias as well as execute \"git help cmd\"\nMaybe something similar can be done for non built-ins that are missing\nman-pages / html-docs\n\nCurrently, you may \"git-foo --help\" directly or use \"git foo -h\"\ninstead of \"git foo --help\" but this may be confusing to users\n\nOn Mon, Dec 20, 2021 at 12:54 PM Ævar Arnfjörð Bjarmason\n wrote:\n>\n>\n> On Sat, Dec 18 2021, Sean Allred wrote:\n>\n> > Hi folks,\n> >\n> > I've got a custom subcommand I'm distributing in my company to\n> > integrate with our bug-tracker. It's a pretty robust utility and has\n> > its own help function, but running `git foo --help` doesn't pass\n> > --help to my git-foo utility. I asked a question[1] about this\n> > scenario on the Windows fork and they directed me upstream.\n> >\n> > It sounds like `git foo --help` is internally consumed as `git help\n> > foo`, which forwards requests to info/man/web handlers per config.\n> > Being on Windows and knowing my peers as I do, the vast majority of my\n> > users won't be familiar with info or man. The HTML documentation used\n> > by the web handler is in a Git4Win-controlled installation directory\n> > that I'd really rather not touch/maintain. I really just want `git foo\n> > --help` to call `git-foo --help`.\n> >\n> > What's the best way to go about this?\n> >\n> > In the event the best next step is to start a patch, does it sound\n> > reasonable to simply not perform this `git foo --help` -> `git help\n> > foo` transformation for non-builtins? Or, while I don't relish the\n> > idea, would some kind of config option be needed?\n> >\n> > Best,\n> > Sean Allred\n> >\n> > [1]: https://github.com/git-for-windows/git/discussions/3553\n>\n> I don't know if there's a solution that'll please everyone here, but\n> it's definitely not narrowing this to built-ins. E.g. \"git send-email\n> --help\" will expect to show the manual, so will \"git annex --help\".\n\n-- \nErik Cervin-Edin\n"},{"id":"444553","messageId":"nycvar.QRO.7.76.6.2112202324110.347@tvgsbejvaqbjf.bet","threadId":"57116","inReplyTo":"CABceR4ZW4rRWZnH0ZBkWty_H84Z4CmXque_LO+1edETEWrO8PQ@mail.gmail.com","subject":"Re: Custom subcommand help handlers","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2021-12-20T22:39:23Z","receivedAt":"2021-12-20T22:39:29Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Sean,\n\nOn Sat, 18 Dec 2021, Sean Allred wrote:\n\n> I've got a custom subcommand I'm distributing in my company to integrate\n> with our bug-tracker. It's a pretty robust utility and has its own help\n> function, but running `git foo --help` doesn't pass --help to my git-foo\n> utility. I asked a question[1] about this scenario on the Windows fork\n> and they directed me upstream.\n>\n> It sounds like `git foo --help` is internally consumed as `git help\n> foo`, which forwards requests to info/man/web handlers per config.\n> Being on Windows and knowing my peers as I do, the vast majority of my\n> users won't be familiar with info or man. The HTML documentation used\n> by the web handler is in a Git4Win-controlled installation directory\n> that I'd really rather not touch/maintain. I really just want `git foo\n> --help` to call `git-foo --help`.\n>\n> What's the best way to go about this?\n>\n> In the event the best next step is to start a patch, does it sound\n> reasonable to simply not perform this `git foo --help` -> `git help\n> foo` transformation for non-builtins? Or, while I don't relish the\n> idea, would some kind of config option be needed?\n\nI think you might need to be a bit more careful than just looking whether\nthe command in question is a built-in or not. It could be delivered as a\nscript or executable inside `libexec/git-core`. So maybe check that,\nsomething like this:\n\n-- snip --\ndiff --git a/git.c b/git.c\nindex c802dfe98004..d609f90cc117 100644\n--- a/git.c\n+++ b/git.c\n@@ -688,6 +688,33 @@ static void strip_extension(const char **argv)\n #define strip_extension(cmd)\n #endif\n\n+static int is_in_git_exec_path(const char *command_name)\n+{\n+\tstruct strbuf path = STRBUF_INIT;\n+\tint ret = 0;\n+\n+\tif (!command_name)\n+\t\treturn 0;\n+\n+\tstrbuf_addf(&path, \"%s/git-%s\", git_exec_path(), command_name);\n+\tret = !access(path.buf, X_OK);\n+\n+#ifdef STRIP_EXTENSION\n+\tif (!ret) {\n+\t\t/*\n+\t\t * If `command_name` ended in `.exe`, strip it, otherwise\n+\t\t * append it.\n+\t\t */\n+\t\tif (!strbuf_strip_suffix(&path, STRIP_EXTENSION))\n+\t\t\tstrbuf_addstr(&path, STRIP_EXTENSION);\n+\t\tret = !access(path.buf, X_OK);\n+\t}\n+#endif\n+\n+\tstrbuf_release(&path);\n+\treturn ret;\n+}\n+\n static void handle_builtin(int argc, const char **argv)\n {\n \tstruct strvec args = STRVEC_INIT;\n@@ -697,8 +724,11 @@ static void handle_builtin(int argc, const char **argv)\n \tstrip_extension(argv);\n \tcmd = argv[0];\n\n+\tbuiltin = get_builtin(cmd);\n+\n \t/* Turn \"git cmd --help\" into \"git help --exclude-guides cmd\" */\n-\tif (argc > 1 && !strcmp(argv[1], \"--help\")) {\n+\tif (argc > 1 && !strcmp(argv[1], \"--help\") &&\n+\t (builtin || is_in_git_exec_path(argv[0]))) {\n \t\tint i;\n\n \t\targv[1] = argv[0];\n@@ -714,7 +744,6 @@ static void handle_builtin(int argc, const char **argv)\n \t\targv = args.v;\n \t}\n\n-\tbuiltin = get_builtin(cmd);\n \tif (builtin)\n \t\texit(run_builtin(builtin, argc, argv));\n \tstrvec_clear(&args);\n-- snap --\n\nOf course, this might break existing users' setups where they ship a Git\ncommand together with a manual page.\n\nA potential remedy against that would be, as you say, a config option.\nMaybe defaulting to the manual page if `help.format` is `man`, otherwise\ndefaulting to passing `--help` to the command.\n\nCiao,\nDscho\n\n>\n> Best,\n> Sean Allred\n>\n> [1]: https://github.com/git-for-windows/git/discussions/3553\n>\n"},{"id":"444555","messageId":"YcEJtOknDjSgxK5j@camp.crustytoothpaste.net","threadId":"57116","inReplyTo":"CA+JQ7M8oxzUAkw-Nv4X+3bJt7cBhsUaqFKd67Y=LNLnv2kgM+Q@mail.gmail.com","subject":"Re: Custom subcommand help handlers","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2021-12-20T22:54:44Z","receivedAt":"2021-12-20T22:54:49Z","isPatch":false,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On 2021-12-20 at 12:37:26, Erik Cervin Edin wrote:\n> It looks like any git cmd --help is transformed into\n> \"git help --exclude-guides cmd\"\n> This is used to differentiate \"git cmd --help\" and \"git help cmd\".\n> \n> It's used with aliases to print the alias as well as execute \"git help cmd\"\n> Maybe something similar can be done for non built-ins that are missing\n> man-pages / html-docs\n\nI don't know that you can effectively distinguish whether there's\ndocumentation for man. It isn't guaranteed that it will exit\ndifferently if the page is missing versus if it encountered an error.\n\nOne thought I have is that on some Unix systems, you can use MANPATH to\nset a list of directories in which to search for manual pages. Maybe\nthere's a standard environment variable that I'm not aware of that would\nprovide a similar functionality.\n\nI should point out that in most cases on Unix, it _is_ expected that you\ninstall your manual pages into the same place as everyone else, so in\nthis case, installing the HTML documentation alongside Git's may be the\nbest solution.\n-- \nbrian m. carlson (he/him or they/them)\nToronto, Ontario, CA\n"},{"id":"444556","messageId":"xmqqa6guub9n.fsf@gitster.g","threadId":"57116","inReplyTo":"YcEJtOknDjSgxK5j@camp.crustytoothpaste.net","subject":"Re: Custom subcommand help handlers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-12-20T23:06:28Z","receivedAt":"2021-12-20T23:06:37Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"\"brian m. carlson\" writes:\n\n> I should point out that in most cases on Unix, it _is_ expected that you\n> install your manual pages into the same place as everyone else, so in\n> this case, installing the HTML documentation alongside Git's may be the\n> best solution.\n\nYup, that sounds like the most sensible way to do things.\n"},{"id":"444575","messageId":"211221.86k0fysm0i.gmgdl@evledraar.gmail.com","threadId":"57116","inReplyTo":"nycvar.QRO.7.76.6.2112202324110.347@tvgsbejvaqbjf.bet","subject":"Re: Custom subcommand help handlers","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-12-21T02:51:58Z","receivedAt":"2021-12-21T02:57:21Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Mon, Dec 20 2021, Johannes Schindelin wrote:\n\n> Hi Sean,\n>\n> On Sat, 18 Dec 2021, Sean Allred wrote:\n>\n>> I've got a custom subcommand I'm distributing in my company to integrate\n>> with our bug-tracker. It's a pretty robust utility and has its own help\n>> function, but running `git foo --help` doesn't pass --help to my git-foo\n>> utility. I asked a question[1] about this scenario on the Windows fork\n>> and they directed me upstream.\n>>\n>> It sounds like `git foo --help` is internally consumed as `git help\n>> foo`, which forwards requests to info/man/web handlers per config.\n>> Being on Windows and knowing my peers as I do, the vast majority of my\n>> users won't be familiar with info or man. The HTML documentation used\n>> by the web handler is in a Git4Win-controlled installation directory\n>> that I'd really rather not touch/maintain. I really just want `git foo\n>> --help` to call `git-foo --help`.\n>>\n>> What's the best way to go about this?\n>>\n>> In the event the best next step is to start a patch, does it sound\n>> reasonable to simply not perform this `git foo --help` -> `git help\n>> foo` transformation for non-builtins? Or, while I don't relish the\n>> idea, would some kind of config option be needed?\n>\n> I think you might need to be a bit more careful than just looking whether\n> the command in question is a built-in or not. It could be delivered as a\n> script or executable inside `libexec/git-core`. So maybe check that,\n> something like this:\n>\n> -- snip --\n> diff --git a/git.c b/git.c\n> index c802dfe98004..d609f90cc117 100644\n> --- a/git.c\n> +++ b/git.c\n> @@ -688,6 +688,33 @@ static void strip_extension(const char **argv)\n> #define strip_extension(cmd)\n> #endif\n>\n> +static int is_in_git_exec_path(const char *command_name)\n> +{\n> +\tstruct strbuf path = STRBUF_INIT;\n> +\tint ret = 0;\n> +\n> +\tif (!command_name)\n> +\t\treturn 0;\n> +\n> +\tstrbuf_addf(&path, \"%s/git-%s\", git_exec_path(), command_name);\n> +\tret = !access(path.buf, X_OK);\n> +\n> +#ifdef STRIP_EXTENSION\n> +\tif (!ret) {\n> +\t\t/*\n> +\t\t * If `command_name` ended in `.exe`, strip it, otherwise\n> +\t\t * append it.\n> +\t\t */\n> +\t\tif (!strbuf_strip_suffix(&path, STRIP_EXTENSION))\n> +\t\t\tstrbuf_addstr(&path, STRIP_EXTENSION);\n> +\t\tret = !access(path.buf, X_OK);\n> +\t}\n> +#endif\n> +\n> +\tstrbuf_release(&path);\n> +\treturn ret;\n> +}\n> +\n> static void handle_builtin(int argc, const char **argv)\n> {\n> \tstruct strvec args = STRVEC_INIT;\n> @@ -697,8 +724,11 @@ static void handle_builtin(int argc, const char **argv)\n> \tstrip_extension(argv);\n> \tcmd = argv[0];\n>\n> +\tbuiltin = get_builtin(cmd);\n> +\n> \t/* Turn \"git cmd --help\" into \"git help --exclude-guides cmd\" */\n> -\tif (argc > 1 && !strcmp(argv[1], \"--help\")) {\n> +\tif (argc > 1 && !strcmp(argv[1], \"--help\") &&\n> +\t (builtin || is_in_git_exec_path(argv[0]))) {\n> \t\tint i;\n>\n> \t\targv[1] = argv[0];\n> @@ -714,7 +744,6 @@ static void handle_builtin(int argc, const char **argv)\n> \t\targv = args.v;\n> \t}\n>\n> -\tbuiltin = get_builtin(cmd);\n> \tif (builtin)\n> \t\texit(run_builtin(builtin, argc, argv));\n> \tstrvec_clear(&args);\n> -- snap --\n>\n> Of course, this might break existing users' setups where they ship a Git\n> command together with a manual page.\n>\n> A potential remedy against that would be, as you say, a config option.\n> Maybe defaulting to the manual page if `help.format` is `man`, otherwise\n> defaulting to passing `--help` to the command.\n\nWhat are the cases that require us to inexpect our --exec-path at\nruntime, as opposed to having a list of commands we know we put there at\n\"install\" time?\n\nThe only ones I can think of are e.g. Debian's packaging which might\ncompile the git with \"git-send-email\", but it won't be there unless you\ninstall \"git-email\" in addition to \"git\".\n\nBut for those cases any such logic would presumably want the hardcoded\nfull list over the dynamic access() check, since e.g. \"git-doc\" on that\nplatform orthagonally installs \"git-send-email.html\" and the like, and\n\"git help send-email\" would presumably like to error saying that we know\nabout git-send-email, we just can't find its documentation, even if we\ncan't find it in --exec-path.\n"},{"id":"444591","messageId":"CA+JQ7M8ofJfnTGn+eFPhW4vL6xi0M7GU-=fvPG2knrvJppU9kQ@mail.gmail.com","threadId":"57116","inReplyTo":"xmqqa6guub9n.fsf@gitster.g","subject":"Re: Custom subcommand help handlers","fromName":"Erik Cervin Edin","fromEmail":"erik@cervined.in","sentAt":"2021-12-21T09:12:25Z","receivedAt":"2021-12-21T09:13:06Z","isPatch":false,"sender":{"key":"erik@cervined.in","avatar":null},"body":"> I should point out that in most cases on Unix, it _is_ expected that you\n> install your manual pages into the same place as everyone else, so in\n> this case, installing the HTML documentation alongside Git's may be the\n> best solution.\n\nI also think this sounds sensible\nA hurdle is that while Unix man pages are well established\nand I'm not aware of a standard or convention around HTML documentation.\n\nOn windows, you can install the HTML pages into\n/mingw64/share/doc/git-doc/\nthe problem is \"git for windows\" default installs in program files\nso admin rights are required.\n\nYou can supply a custom path for HTML pages\ngit -c help.htmlPath=`realpath.exe ~/doc/git/html/` help git-filter-repo\nso an option is for user/admins to move/copy\nall the help documentation to a different path.\n\nAn idea is that if HTML documentation is not found at help.htmlPath\nto look for HTML documentation at the path of the command before failing\nI don't know if that's a good idea but it sounds simple\n\n\n\nOn Tue, Dec 21, 2021 at 12:06 AM Junio C Hamano wrote:\n>\n> \"brian m. carlson\" writes:\n>\n> > I should point out that in most cases on Unix, it _is_ expected that you\n> > install your manual pages into the same place as everyone else, so in\n> > this case, installing the HTML documentation alongside Git's may be the\n> > best solution.\n>\n> Yup, that sounds like the most sensible way to do things.\n"},{"id":"444784","messageId":"nycvar.QRO.7.76.6.2112221640340.347@tvgsbejvaqbjf.bet","threadId":"57116","inReplyTo":"211221.86k0fysm0i.gmgdl@evledraar.gmail.com","subject":"Re: Custom subcommand help handlers","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2021-12-22T16:16:31Z","receivedAt":"2021-12-22T16:16:36Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Ævar,\n\nOn Tue, 21 Dec 2021, Ævar Arnfjörð Bjarmason wrote:\n\n> On Mon, Dec 20 2021, Johannes Schindelin wrote:\n>\n> > On Sat, 18 Dec 2021, Sean Allred wrote:\n> >\n> >> I've got a custom subcommand I'm distributing in my company to integrate\n> >> with our bug-tracker. It's a pretty robust utility and has its own help\n> >> function, but running `git foo --help` doesn't pass --help to my git-foo\n> >> utility. [...]\n> >>\n> >> What's the best way to go about this?\n> >\n> > I think you might need to be a bit more careful than just looking whether\n> > the command in question is a built-in or not. It could be delivered as a\n> > script or executable inside `libexec/git-core`. So maybe check that,\n> > something like this:\n> >\n> > -- snip --\n> > [...]\n> > -- snap --\n> >\n> > Of course, this might break existing users' setups where they ship a Git\n> > command together with a manual page.\n> >\n> > A potential remedy against that would be, as you say, a config option.\n> > Maybe defaulting to the manual page if `help.format` is `man`, otherwise\n> > defaulting to passing `--help` to the command.\n>\n> What are the cases that require us to inexpect our --exec-path at\n> runtime, as opposed to having a list of commands we know we put there at\n> \"install\" time?\n\nIt is a simple solution. Why even suggest a complex alternative, I wonder.\n\nCiao,\nJohannes\n"},{"id":"444785","messageId":"nycvar.QRO.7.76.6.2112221717440.347@tvgsbejvaqbjf.bet","threadId":"57116","inReplyTo":"xmqqa6guub9n.fsf@gitster.g","subject":"Re: Custom subcommand help handlers","fromName":"Johannes Schindelin","fromEmail":"johannes.schindelin@gmx.de","sentAt":"2021-12-22T16:19:58Z","receivedAt":"2021-12-22T16:20:15Z","isPatch":false,"sender":{"key":"johannes.schindelin@gmx.de","avatar":"https://avatars.githubusercontent.com/u/127790?v=4"},"body":"Hi Junio,\n\nOn Mon, 20 Dec 2021, Junio C Hamano wrote:\n\n> \"brian m. carlson\" writes:\n>\n> > I should point out that in most cases on Unix, it _is_ expected that you\n> > install your manual pages into the same place as everyone else, so in\n> > this case, installing the HTML documentation alongside Git's may be the\n> > best solution.\n>\n> Yup, that sounds like the most sensible way to do things.\n\nSo what about `~/bin/git-my-reply-to-junio`? Do we expect people to write\na manual page and install it into `~/man/man1` and for `man` to pick that\nup?\n\nIn other words: I think you're trying to make the problem sound less\ncomplex than it is.\n\nCiao,\nDscho\n"},{"id":"444789","messageId":"211222.865yrgplu9.gmgdl@evledraar.gmail.com","threadId":"57116","inReplyTo":"nycvar.QRO.7.76.6.2112221640340.347@tvgsbejvaqbjf.bet","subject":"Re: Custom subcommand help handlers","fromName":"Ævar Arnfjörð Bjarmason","fromEmail":"avarab@gmail.com","sentAt":"2021-12-22T17:44:38Z","receivedAt":"2021-12-22T17:53:55Z","isPatch":false,"sender":{"key":"avarab@gmail.com","avatar":"https://avatars.githubusercontent.com/u/45301?v=4"},"body":"\nOn Wed, Dec 22 2021, Johannes Schindelin wrote:\n\n> Hi Ævar,\n>\n> On Tue, 21 Dec 2021, Ævar Arnfjörð Bjarmason wrote:\n>\n>> On Mon, Dec 20 2021, Johannes Schindelin wrote:\n>>\n>> > On Sat, 18 Dec 2021, Sean Allred wrote:\n>> >\n>> >> I've got a custom subcommand I'm distributing in my company to integrate\n>> >> with our bug-tracker. It's a pretty robust utility and has its own help\n>> >> function, but running `git foo --help` doesn't pass --help to my git-foo\n>> >> utility. [...]\n>> >>\n>> >> What's the best way to go about this?\n>> >\n>> > I think you might need to be a bit more careful than just looking whether\n>> > the command in question is a built-in or not. It could be delivered as a\n>> > script or executable inside `libexec/git-core`. So maybe check that,\n>> > something like this:\n>> >\n>> > -- snip --\n>> > [...]\n>> > -- snap --\n>> >\n>> > Of course, this might break existing users' setups where they ship a Git\n>> > command together with a manual page.\n>> >\n>> > A potential remedy against that would be, as you say, a config option.\n>> > Maybe defaulting to the manual page if `help.format` is `man`, otherwise\n>> > defaulting to passing `--help` to the command.\n>>\n>> What are the cases that require us to inexpect our --exec-path at\n>> runtime, as opposed to having a list of commands we know we put there at\n>> \"install\" time?\n>\n> It is a simple solution. Why even suggest a complex alternative, I wonder.\n\nYou're suggesting the more complex alternative.\n\nWe already have a way in that same file to dump both built-ins and other\nknown commands:\n\n\tgit --list-cmds=builtins\n\tgit --list-cmds=main\n\nAnd isn't your is_in_git_exec_path() basically a re-implementation of\nwhat we already get from:\n\n\tgit --list-cmds=others\n\n?\n\nHence my question. I.e. if you don't have git-send-email installed why\nwould you take your is_in_git_exec_path()? I.e. start treating it as\n\"others\" would be treated. We know it's ours, it's just not installed at\nthe moment.\n\nBut those aren't the same thing, so either you didn't know that we have\nthis data already, or the difference is important for some reason you\nhaven't explained.\n"},{"id":"444818","messageId":"xmqqczloju0q.fsf@gitster.g","threadId":"57116","inReplyTo":"nycvar.QRO.7.76.6.2112221717440.347@tvgsbejvaqbjf.bet","subject":"Re: Custom subcommand help handlers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-12-22T19:53:41Z","receivedAt":"2021-12-22T19:53:46Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Johannes Schindelin writes:\n\n> On Mon, 20 Dec 2021, Junio C Hamano wrote:\n>\n>> \"brian m. carlson\" writes:\n>>\n>> > I should point out that in most cases on Unix, it _is_ expected that you\n>> > install your manual pages into the same place as everyone else, so in\n>> > this case, installing the HTML documentation alongside Git's may be the\n>> > best solution.\n>>\n>> Yup, that sounds like the most sensible way to do things.\n>\n> So what about `~/bin/git-my-reply-to-junio`? Do we expect people to write\n> a manual page and install it into `~/man/man1` and for `man` to pick that\n> up?\n\nYes, if they write one, and then tell man that you have extra\nmanpages there via MANPATH.\n\nI expect people *not* to write a manual page in practice for such a\nthing, though ;-)\n"},{"id":"444843","messageId":"CA+JQ7M-8LydHMCgMYGP9LNMJMWk_-7LLYa5WEMMb_QMpeF-+Ag@mail.gmail.com","threadId":"57116","inReplyTo":"xmqqczloju0q.fsf@gitster.g","subject":"Re: Custom subcommand help handlers","fromName":"Erik Cervin Edin","fromEmail":"erik@cervined.in","sentAt":"2021-12-22T23:40:53Z","receivedAt":"2021-12-22T23:41:31Z","isPatch":false,"sender":{"key":"erik@cervined.in","avatar":null},"body":"Another observation.\n\nThis also applies to external aliases\n git -c alias.fr='!git-filter-repo' fr --help\nreturns\n 'fr' is aliased to '!git-filter-repo'\n w exit code 0\n\nOn Wed, Dec 22, 2021 at 8:53 PM Junio C Hamano wrote:\n>\n> Johannes Schindelin writes:\n>\n> > On Mon, 20 Dec 2021, Junio C Hamano wrote:\n> >\n> >> \"brian m. carlson\" writes:\n> >>\n> >> > I should point out that in most cases on Unix, it _is_ expected that you\n> >> > install your manual pages into the same place as everyone else, so in\n> >> > this case, installing the HTML documentation alongside Git's may be the\n> >> > best solution.\n> >>\n> >> Yup, that sounds like the most sensible way to do things.\n> >\n> > So what about `~/bin/git-my-reply-to-junio`? Do we expect people to write\n> > a manual page and install it into `~/man/man1` and for `man` to pick that\n> > up?\n>\n> Yes, if they write one, and then tell man that you have extra\n> manpages there via MANPATH.\n>\n> I expect people *not* to write a manual page in practice for such a\n> thing, though ;-)\n"},{"id":"444846","messageId":"xmqq35mkdvsu.fsf@gitster.g","threadId":"57116","inReplyTo":"CA+JQ7M-8LydHMCgMYGP9LNMJMWk_-7LLYa5WEMMb_QMpeF-+Ag@mail.gmail.com","subject":"Re: Custom subcommand help handlers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-12-23T00:11:45Z","receivedAt":"2021-12-23T00:11:53Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Erik Cervin Edin writes:\n\n> Another observation.\n>\n> This also applies to external aliases\n> git -c alias.fr='!git-filter-repo' fr --help\n> returns\n> 'fr' is aliased to '!git-filter-repo'\n> w exit code 0\n\nI do not know what your 'w' is. To me I get\n\n $ git -c alias.fr='!git-filter-repo' fr --help\n 'fr' is aliased to '!git-filter-repo'\n\nwhich is consistent with what I get for other aliases, e.g.\n\n $ git -c alias.lg='log --oneline' lg --help\n 'lg' is aliased to 'log --oneline'\n\nfolowed by whatever \"log --help\" would give us.\n\nSo hopefully when your 'w' learns to show the documentation for\n'git-filter-repo' command, such an alias would also work as\nexpected, no?\n\nAnyway, unlike \"man\" and \"info\" where there is a standard way to\ntell the command that \"I have documentation pages in these places\"\nso that additional documentation can be installed to locations the\nuser chooses (and has access to), the \"web\" format viewers are\ninvoked without such customizability, i.e. in builtin/help.c, we see\nthis code snippet:\n\nstatic void get_html_page_path(struct strbuf *page_path, const char *page)\n{\n\tstruct stat st;\n\tchar *to_free = NULL;\n\n\tif (!html_path)\n\t\thtml_path = to_free = system_path(GIT_HTML_PATH);\n\n\t/*\n\t * Check that the page we're looking for exists.\n\t */\n\tif (!strstr(html_path, \"://\")) {\n\t\tif (stat(mkpath(\"%s/%s.html\", html_path, page), &st)\n\t\t || !S_ISREG(st.st_mode))\n\t\t\tdie(\"'%s/%s.html': documentation file not found.\",\n\t\t\t\thtml_path, page);\n\t}\n\n\tstrbuf_init(page_path, 0);\n\tstrbuf_addf(page_path, \"%s/%s.html\", html_path, page);\n\tfree(to_free);\n}\n\nIt may not be a bad idea to extand the function to understand a new\nGIT_HTML_PATH environment variable, which can be a colon-separated\nlist of directories just like MANPATH and INFOPATH are. It would be\nrather trivial to update the block with a call to stat() above to a\nloop over these directories.\n\n\n\n"},{"id":"444857","messageId":"CA+JQ7M826Wj3Lq8XEr1w9quj9vM6EWH9ivSfvaXYrkh1dA2vfg@mail.gmail.com","threadId":"57116","inReplyTo":"xmqq35mkdvsu.fsf@gitster.g","subject":"Re: Custom subcommand help handlers","fromName":"Erik Cervin Edin","fromEmail":"erik@cervined.in","sentAt":"2021-12-23T11:33:53Z","receivedAt":"2021-12-23T11:34:31Z","isPatch":false,"sender":{"key":"erik@cervined.in","avatar":null},"body":"> I do not know what your 'w' is.\n\nSorry, I was unclear.\nWith exit code 0\n\nI was experimenting to see if you could use\nan external alias to force --help to be passed to cmd.\n\nBut you can't because\n if (!exclude_guides || alias[0] == '!') {\n printf_ln(_(\"'%s' is aliased to '%s'\"), cmd, alias);\n free(alias);\n exit(0);\n }\n\nWhich is probably reasonable\n\n\nOn Thu, Dec 23, 2021 at 1:11 AM Junio C Hamano wrote:\n>\n> Erik Cervin Edin writes:\n>\n> > Another observation.\n> >\n> > This also applies to external aliases\n> > git -c alias.fr='!git-filter-repo' fr --help\n> > returns\n> > 'fr' is aliased to '!git-filter-repo'\n> > w exit code 0\n>\n> I do not know what your 'w' is. To me I get\n>\n> $ git -c alias.fr='!git-filter-repo' fr --help\n> 'fr' is aliased to '!git-filter-repo'\n>\n> which is consistent with what I get for other aliases, e.g.\n>\n> $ git -c alias.lg='log --oneline' lg --help\n> 'lg' is aliased to 'log --oneline'\n>\n> folowed by whatever \"log --help\" would give us.\n>\n> So hopefully when your 'w' learns to show the documentation for\n> 'git-filter-repo' command, such an alias would also work as\n> expected, no?\n>\n> Anyway, unlike \"man\" and \"info\" where there is a standard way to\n> tell the command that \"I have documentation pages in these places\"\n> so that additional documentation can be installed to locations the\n> user chooses (and has access to), the \"web\" format viewers are\n> invoked without such customizability, i.e. in builtin/help.c, we see\n> this code snippet:\n>\n> static void get_html_page_path(struct strbuf *page_path, const char *page)\n> {\n> struct stat st;\n> char *to_free = NULL;\n>\n> if (!html_path)\n> html_path = to_free = system_path(GIT_HTML_PATH);\n>\n> /*\n> * Check that the page we're looking for exists.\n> */\n> if (!strstr(html_path, \"://\")) {\n> if (stat(mkpath(\"%s/%s.html\", html_path, page), &st)\n> || !S_ISREG(st.st_mode))\n> die(\"'%s/%s.html': documentation file not found.\",\n> html_path, page);\n> }\n>\n> strbuf_init(page_path, 0);\n> strbuf_addf(page_path, \"%s/%s.html\", html_path, page);\n> free(to_free);\n> }\n>\n> It may not be a bad idea to extand the function to understand a new\n> GIT_HTML_PATH environment variable, which can be a colon-separated\n> list of directories just like MANPATH and INFOPATH are. It would be\n> rather trivial to update the block with a call to stat() above to a\n> loop over these directories.\n>\n>\n>\n"},{"id":"444859","messageId":"032aced5-4c50-76f7-9ab6-580ffa5775a5@iee.email","threadId":"57116","inReplyTo":"xmqqczloju0q.fsf@gitster.g","subject":"Re: Custom subcommand help handlers","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-12-23T15:07:48Z","receivedAt":"2021-12-23T15:07:51Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 22/12/2021 19:53, Junio C Hamano wrote:\n> Johannes Schindelin writes:\n>\n>> On Mon, 20 Dec 2021, Junio C Hamano wrote:\n>>\n>>> \"brian m. carlson\" writes:\n>>>\n>>>> I should point out that in most cases on Unix, it _is_ expected that you\n>>>> install your manual pages into the same place as everyone else, so in\n>>>> this case, installing the HTML documentation alongside Git's may be the\n>>>> best solution.\n>>> Yup, that sounds like the most sensible way to do things.\n>> So what about `~/bin/git-my-reply-to-junio`? Do we expect people to write\n>> a manual page and install it into `~/man/man1` and for `man` to pick that\n>> up?\n> Yes, if they write one, and then tell man that you have extra\n> manpages there via MANPATH.\n>\n> I expect people *not* to write a manual page in practice for such a\n> thing, though ;-)\n\nIn the very original use case reported in the git for windows issues\npages, I understood it that the provider of the git-foo script expected\nthat they would include some detection and response to the --help being\ngiven as an option.\n\nThey had the issue that their windows users, using Git for Windows, do\nnot have the `man` package installed. Rather the `web` help of using the\n.html version of the man page is used (needs administrator install in\nsome case). So user commands would need to provide both the man page for\nLinux systems and some process to get the html equivalent into the right\nfolder - this latter case was the problem step. \n\nThe expectation from the XY-Problem was that if the html (and possibly,\nby implication, the man page) was not found by git, that the --help\noption would be passed to the command itself for it the command to\nprocess (or ignore)..\n\nIt is a bit of a rabbit hole.\n\nPhilip\n"},{"id":"444892","messageId":"xmqqh7ay6en7.fsf@gitster.g","threadId":"57116","inReplyTo":"032aced5-4c50-76f7-9ab6-580ffa5775a5@iee.email","subject":"Re: Custom subcommand help handlers","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2021-12-24T00:16:28Z","receivedAt":"2021-12-24T00:16:31Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Philip Oakley writes:\n\n> They had the issue that their windows users, using Git for Windows, do\n> not have the `man` package installed. Rather the `web` help of using the\n> .html version of the man page is used (needs administrator install in\n> some case). So user commands would need to provide both the man page for\n> Linux systems and some process to get the html equivalent into the right\n> folder - this latter case was the problem step.\n\nSo are they willing to prepare `web` help pages, because that is\nwhat the users of Git for Windows are already familiar with, if \"git\nfoo --help\" is capable of showing it, just like \"git commit --help\"\nshows the `web` help page for the subcommand?\n\nAs I said elsewhere on this thread, lack of equivalent for MANPATH\nand INFOPATH makes `web` help harder to customize in that direction,\nbut that is a problem we can solve in our code. Once it is there,\nthey can let the user install their `web` help pages into somewhere\nthe user has write access to and point at the \"folder\" with\nGIT_HTMLPATH, I would presume?\n\nThanks.\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n"},{"id":"444902","messageId":"7c98ad08-046c-d2c2-2bfa-e6b559f41fd3@iee.email","threadId":"57116","inReplyTo":"xmqqh7ay6en7.fsf@gitster.g","subject":"Re: Custom subcommand help handlers","fromName":"Philip Oakley","fromEmail":"philipoakley@iee.email","sentAt":"2021-12-24T11:26:04Z","receivedAt":"2021-12-24T11:26:10Z","isPatch":false,"sender":{"key":"philipoakley@iee.email","avatar":"https://avatars.githubusercontent.com/u/914343?v=4"},"body":"On 24/12/2021 00:16, Junio C Hamano wrote:\n> Philip Oakley writes:\n>\n>> They had the issue that their windows users, using Git for Windows, do\n>> not have the `man` package installed. Rather the `web` help of using the\n>> .html version of the man page is used (needs administrator install in\n>> some case). So user commands would need to provide both the man page for\n>> Linux systems and some process to get the html equivalent into the right\n>> folder - this latter case was the problem step.\n> So are they willing to prepare `web` help pages, because that is\n> what the users of Git for Windows are already familiar with, if \"git\n> foo --help\" is capable of showing it, just like \"git commit --help\"\n> shows the `web` help page for the subcommand?\n>\n> As I said elsewhere on this thread, lack of equivalent for MANPATH\n> and INFOPATH makes `web` help harder to customize in that direction,\n> but that is a problem we can solve in our code. Once it is there,\n> they can let the user install their `web` help pages into somewhere\n> the user has write access to and point at the \"folder\" with\n> GIT_HTMLPATH, I would presume?\n>\n> Thanks.\n>\nI'm not sure if they are willing to create web versions of the man page\nor not. The request was that we should let their code decide by passing\nthe --help option so they could link out to whatever process they have -\nmaybe it's a SharePoint server with fancy presentations (I never liked\nthem, but many places have drunk the cool aid).\n\nHaving an alternate GIT_HTMLPATH could help some users who do have html\ndocuments, but I was cautious about letting ourselves over automate the\nmechanisation and still leave the users out of the picture.\n\nHopefully Sean will be able to clarify if I've misunderstood the details\nof their problems.\n\nPhilip\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n>\n"},{"id":"448322","messageId":"87tud3wwlx.fsf@gmail.com","threadId":"57116","inReplyTo":"nycvar.QRO.7.76.6.2112202324110.347@tvgsbejvaqbjf.bet","subject":"Re: Custom subcommand help handlers","fromName":"Sean Allred","fromEmail":"allred.sean@gmail.com","sentAt":"2022-02-12T22:23:52Z","receivedAt":"2022-02-12T22:25:54Z","isPatch":false,"sender":{"key":"allred.sean@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2082195?v=4"},"body":"\n> I think you might need to be a bit more careful than just looking whether\n> the command in question is a built-in or not. It could be delivered as a\n> script or executable inside `libexec/git-core`.\n\nI apologize, yes -- I used 'built-in' as a synonym for 'distributed with\nGit', but this of course is not how this project uses the term :-)\n\n> Of course, this might break existing users' setups where they ship a Git\n> command together with a manual page.\n>\n> A potential remedy against that would be, as you say, a config option.\n> Maybe defaulting to the manual page if `help.format` is `man`, otherwise\n> defaulting to passing `--help` to the command.\n\nIt's worth noting that Git for Windows does not distribute a\nmanpage-viewer :-(\n\n--\nSean Allred\n"},{"id":"448324","messageId":"87pmnrww1a.fsf@gmail.com","threadId":"57116","inReplyTo":"7c98ad08-046c-d2c2-2bfa-e6b559f41fd3@iee.email","subject":"Re: Custom subcommand help handlers","fromName":"Sean Allred","fromEmail":"allred.sean@gmail.com","sentAt":"2022-02-12T22:29:39Z","receivedAt":"2022-02-12T22:38:16Z","isPatch":false,"sender":{"key":"allred.sean@gmail.com","avatar":"https://avatars.githubusercontent.com/u/2082195?v=4"},"body":"\nPhilip Oakley writes:\n\n> On 24/12/2021 00:16, Junio C Hamano wrote:\n>> Philip Oakley writes:\n>>\n>>> They had the issue that their windows users, using Git for Windows, do\n>>> not have the `man` package installed. Rather the `web` help of using the\n>>> .html version of the man page is used (needs administrator install in\n>>> some case). So user commands would need to provide both the man page for\n>>> Linux systems and some process to get the html equivalent into the right\n>>> folder - this latter case was the problem step.\n>> So are they willing to prepare `web` help pages, because that is\n>> what the users of Git for Windows are already familiar with, if \"git\n>> foo --help\" is capable of showing it, just like \"git commit --help\"\n>> shows the `web` help page for the subcommand?\n>>\n>> As I said elsewhere on this thread, lack of equivalent for MANPATH\n>> and INFOPATH makes `web` help harder to customize in that direction,\n>> but that is a problem we can solve in our code. Once it is there,\n>> they can let the user install their `web` help pages into somewhere\n>> the user has write access to and point at the \"folder\" with\n>> GIT_HTMLPATH, I would presume?\n>>\n>> Thanks.\n>>\n> I'm not sure if they are willing to create web versions of the man page\n> or not. The request was that we should let their code decide by passing\n> the --help option so they could link out to whatever process they have -\n> maybe it's a SharePoint server with fancy presentations (I never liked\n> them, but many places have drunk the cool aid).\n>\n> Having an alternate GIT_HTMLPATH could help some users who do have html\n> documents, but I was cautious about letting ourselves over automate the\n> mechanisation and still leave the users out of the picture.\n>\n> Hopefully Sean will be able to clarify if I've misunderstood the details\n> of their problems.\n\nSorry for my delayed responses -- I lost the battle to make Gmail do\nwhat I wanted and needed to set up an alternative email client. This\ntook more time than I care to admit :-)\n\nYes, the core of the issue is that Git (for Windows, at least, but\nevidently this also applies to normal Git) looks in one spot for HTML\nhelp pages. We'd be willing to create the documentation in HTML format\nif that means making `git foo --help` work, but needing to drop these in\nthe installation directory of Git for Windows raises questions of how we\nkeep both Git and the documentation for our tool up-to-date. (This is\nassuming we can hack around the obvious 'admin privileges needed'\nproblem.)\n\nHaving a GIT_HTMLPATH variable could resolve this problem for our\nuse-case (provided that the resolution is similar to PATH). Making this\na normal PATH-like variable (with support for multiple paths as you\nwould see with `echo $PATH`) sounds like a good, extensible path (hah)\nforward.\n\n--\nSean Allred\n"}]}