{"thread":{"id":"63308","subject":"Bug report: Minor glitch in \"git help\" error message","startedAt":"2025-04-17T22:56:53Z","lastAt":"2025-04-18T13:27:49Z","messageCount":5,"participants":["Keith Thompson","Junio C Hamano","Jeff King"],"isPatch":false,"patchVersion":null,"patchTotal":null},"messages":[{"id":"516360","messageId":"CAAHpriMkqapiJuUGimn-i8SqcZmvmc=Wpk6oUr844uAkCYgMxA@mail.gmail.com","threadId":"63308","inReplyTo":null,"subject":"Bug report: Minor glitch in \"git help\" error message","fromName":"Keith Thompson","fromEmail":"keith.s.thompson@gmail.com","sentAt":"2025-04-17T22:56:37Z","receivedAt":"2025-04-17T22:56:53Z","isPatch":false,"sender":{"key":"keith.s.thompson@gmail.com","avatar":"https://gravatar.com/avatar/2cd597778c4fcea958f6ff673882f768bd9506a95bc509925cb7eff718601cd5?d=mp&s=160"},"body":"Thank you for filling out a Git bug report!\nPlease answer the following questions to help us understand your issue.\n\nWhat did you do before the bug happened? (Steps to reproduce your issue)\ngit help nosuchcommand\n\nWhat did you expect to happen? (Expected behavior)\nAn error message: \"No manual entry for git-nosuchcommand\"\n\nWhat happened instead? (Actual behavior)\nAn error message: \"No manual entry for gitnosuchcommand\"\n\nWhat's different between what you expected and what actually happened?\nThe hyphen.\n\nIf \"nosuchcommand\" were a git command, the man page would be\nreadable by typing \"man git-nosuchcommand\". The error message\nshould reflect that. (The error message is actually produced\nby the \"man\" command.)\n\nAnything else you want to add:\nProposed patch (works on my system):\n\n```\ncommit 148f2e07a7dbdbe72fa0bd4340b76cba12a19a24 (HEAD -> fix-help-bug)\nAuthor: Keith Thompson \nDate: 2025-04-17 15:35:44 -0700\n\n Fix \"git help\" message for nonexistent subcommand\n\ndiff --git builtin/help.c builtin/help.c\nindex c257079ceb..792549864f 100644\n--- builtin/help.c\n+++ builtin/help.c\n@@ -450,7 +450,7 @@ static const char *cmd_to_page(const char *git_cmd)\n else if (!strcmp(\"scalar\", git_cmd))\n return xstrdup(git_cmd);\n else\n- return xstrfmt(\"git%s\", git_cmd);\n+ return xstrfmt(\"git-%s\", git_cmd);\n }\n\n static void setup_man_path(void)\n```\n\nPlease review the rest of the bug report below.\nYou can delete any lines you don't wish to share.\n\n\n[System Info]\ngit version:\ngit version 2.49.0\ncpu: x86_64\nbuilt from commit: 683c54c999c301c2cd6f715c411407c413b1d84e\nsizeof-long: 8\nsizeof-size_t: 8\nshell-path: /bin/sh\nlibcurl: 8.5.0\nOpenSSL: OpenSSL 3.0.13 30 Jan 2024\nzlib: 1.3\nuname: Linux 6.11.0-24-generic #24~24.04.1-Ubuntu SMP PREEMPT_DYNAMIC\nTue Mar 25 20:14:34 UTC 2 x86_64\ncompiler info: gnuc: 13.3\nlibc info: glibc: 2.39\n$SHELL (typically, interactive shell): /o/bin/bash\n\n\n[Enabled Hooks]\n"},{"id":"516361","messageId":"xmqq5xj2clcx.fsf@gitster.g","threadId":"63308","inReplyTo":"CAAHpriMkqapiJuUGimn-i8SqcZmvmc=Wpk6oUr844uAkCYgMxA@mail.gmail.com","subject":"Re: Bug report: Minor glitch in \"git help\" error message","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-04-18T01:24:46Z","receivedAt":"2025-04-18T01:24:48Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Keith Thompson writes:\n\n> What did you do before the bug happened? (Steps to reproduce your issue)\n> git help nosuchcommand\n>\n> What did you expect to happen? (Expected behavior)\n> An error message: \"No manual entry for git-nosuchcommand\"\n>\n> What happened instead? (Actual behavior)\n> An error message: \"No manual entry for gitnosuchcommand\"\n\nI am of two minds. When \"git help\" is asked for commands, your\nsuggestion does make sense, i.e.\n\n $ git help dog-file\n No manual entry for gitdog-file\n\nAnd these two are moral equivalents.\n\n $ git help cat-file\n $ man git-cat-file\n\nBut \"git help\" can ask for things other than subcommands.\nFor example, these two are equivalents.\n\n $ git help glossary\n $ man gitglossary\n\nNotice the lack of \"-\" there?\n\n> If \"nosuchcommand\" were a git command, the man page would be\n> readable by typing \"man git-nosuchcommand\". The error message\n> should reflect that. (The error message is actually produced\n> by the \"man\" command.)\n\nIn other words, if \"nosuchguide\" were a concept with guide, the man\npage is readable by \"man gitnosuchguide\", and the error message does\nreflect it.\n\nUnlike \"git foo --help\", where it is clear that the user expected a\nsubommand \"foo\", when the user says \"git help foo\", we cannot tell\nwhether the user asked for documentation for a command or a concept\nguide, so adding \"-\" there is a bit like robbing Peter to pay Paul.\n\nThanks for a report.\n\n\n"},{"id":"516362","messageId":"CAAHpriNYikDFwiTpjZEupG4yWOkbzW5DnBcsUnBKkfxxxtWNkw@mail.gmail.com","threadId":"63308","inReplyTo":"xmqq5xj2clcx.fsf@gitster.g","subject":"Re: Bug report: Minor glitch in \"git help\" error message","fromName":"Keith Thompson","fromEmail":"keith.s.thompson@gmail.com","sentAt":"2025-04-18T03:52:10Z","receivedAt":"2025-04-18T03:52:23Z","isPatch":false,"sender":{"key":"keith.s.thompson@gmail.com","avatar":"https://gravatar.com/avatar/2cd597778c4fcea958f6ff673882f768bd9506a95bc509925cb7eff718601cd5?d=mp&s=160"},"body":"On Thu, Apr 17, 2025 at 6:24 PM Junio C Hamano wrote:\n>\n> Keith Thompson writes:\n>\n> > What did you do before the bug happened? (Steps to reproduce your issue)\n> > git help nosuchcommand\n> >\n> > What did you expect to happen? (Expected behavior)\n> > An error message: \"No manual entry for git-nosuchcommand\"\n> >\n> > What happened instead? (Actual behavior)\n> > An error message: \"No manual entry for gitnosuchcommand\"\n>\n> I am of two minds. When \"git help\" is asked for commands, your\n> suggestion does make sense, i.e.\n>\n> $ git help dog-file\n> No manual entry for gitdog-file\n>\n> And these two are moral equivalents.\n>\n> $ git help cat-file\n> $ man git-cat-file\n>\n> But \"git help\" can ask for things other than subcommands.\n> For example, these two are equivalents.\n>\n> $ git help glossary\n> $ man gitglossary\n>\n> Notice the lack of \"-\" there?\n\nIndeed. I've just learned several things that I either didn't know\nor had forgotten:\n\n* \"git help foo\" works for values of \"foo\" that aren't command names,\n like \"glossary\" or \"cli\".\n* \"git help subcommand\" directly invokes \"man git-subcommand\".\n* \"git help topic\" directly invokes \"man gittopic\".\n\nClearly, \"git help\" knows whether the user wanted a subcommand or a\ntopic if it's something that exists. If it isn't, \"git help\" has no\nway of knowing what was intended.\n\nSome proposed solutions, none of which I really like (except maybe\nthe first):\n\n* Assume that the unrecognized word is a subcommand name. There will\n be errors (a message referring to \"git-topic\" that should have been\n \"gittopic\"), but I speculate that *most* (mistyped) arguments are\n command names.\n\n* Produce an error message like:\n \"No such manual entry for git-foo or gitfoo\"\n Problem: The error message comes directly from the \"man\" command,\n which can't be persuaded to produce the above message.\n Probably more effort than it's worth, and a potential new source\n of bugs.\n\n* Construct the man page names the same way for subcommands and topics,\n so \"git help glossary\" invokes \"man git-glossary\". This is a change\n to long-standing practice, and I don't expect this idea to be taken\n seriously.\n\n* Create aliases for all the topic names, so \"git-glossary.7.gz\"\n is a symlink to \"gitglossary.7.gz\". Likely too confusing, and\n not worthwhile for the sake of a one-character glitch in an error\n message. (Except that I might expect \"man git-cli\" to work, but\n I almost always use Git's help mechanism rather than \"man\".)\n\n\n>\n> > If \"nosuchcommand\" were a git command, the man page would be\n> > readable by typing \"man git-nosuchcommand\". The error message\n> > should reflect that. (The error message is actually produced\n> > by the \"man\" command.)\n>\n> In other words, if \"nosuchguide\" were a concept with guide, the man\n> page is readable by \"man gitnosuchguide\", and the error message does\n> reflect it.\n>\n> Unlike \"git foo --help\", where it is clear that the user expected a\n> subommand \"foo\", when the user says \"git help foo\", we cannot tell\n> whether the user asked for documentation for a command or a concept\n> guide, so adding \"-\" there is a bit like robbing Peter to pay Paul.\n>\n> Thanks for a report.\n>\n>\n"},{"id":"516364","messageId":"20250418091612.GA10441@coredump.intra.peff.net","threadId":"63308","inReplyTo":"CAAHpriNYikDFwiTpjZEupG4yWOkbzW5DnBcsUnBKkfxxxtWNkw@mail.gmail.com","subject":"Re: Bug report: Minor glitch in \"git help\" error message","fromName":"Jeff King","fromEmail":"peff@peff.net","sentAt":"2025-04-18T09:16:12Z","receivedAt":"2025-04-18T09:16:22Z","isPatch":false,"sender":{"key":"peff@peff.net","avatar":"https://avatars.githubusercontent.com/u/45925?v=4"},"body":"On Thu, Apr 17, 2025 at 08:52:10PM -0700, Keith Thompson wrote:\n\n> Some proposed solutions, none of which I really like (except maybe\n> the first):\n> \n> * Assume that the unrecognized word is a subcommand name. There will\n> be errors (a message referring to \"git-topic\" that should have been\n> \"gittopic\"), but I speculate that *most* (mistyped) arguments are\n> command names.\n\nI think the problem is that it's not unrecognized at all by Git. We\ndon't have a list of topic pages, so we just assume any non-command is a\ntopic, and hand if to \"man\". And it is \"man\" that realizes there is no\nsuch page. So you cannot assume up-front, as it would hand the wrong\nname to \"man\". But...\n\n> * Produce an error message like:\n> \"No such manual entry for git-foo or gitfoo\"\n> Problem: The error message comes directly from the \"man\" command,\n> which can't be persuaded to produce the above message.\n> Probably more effort than it's worth, and a potential new source\n> of bugs.\n\nWe could detect a non-zero exit code from \"man\" and print more messages\nafterwards. Something like:\n\n $ git help foo\n No manual entry for gitfoo\n error: no command \"git-foo\" detected, and viewing the concept manual for \"gitfoo\" failed\n\nBut I don't know how reliable that exit code is.\n\nIn Debian's \"man\" implementation, code 16 is documented as \"page not\nfound\". I'd expect most man implementations to at least return non-zero\nfor that case. I would worry a bit about implementations which return\nnon-zero even on success (e.g., if the roff formatter gets SIGPIPE when\nthe pager closes early, would man ever propagate that code? If so, we'd\nget bogus error messages).\n\nThe other complication is that \"man\" is not the only viewer. We might be\nshowing HTML documentation with a browser, or even GNU info pages. And\nyou're less likely to get a good exit code there (e.g., I'd expect most\nbrowser invocations to just remote-control an existing browser to open a\nnew window/tab).\n\n\nI think the most accurate and foolproof thing is that \"git help\" could\ntell what it is doing as it works: it sees that \"foo\" is not a git\ncommand, so it decides to try it as the \"gitfoo\" topic page. It could\nsay so:\n\n $ git help foo\n warning: no command \"git-foo\" found, assuming \"foo\" is a topic\n No manual entry for gitfoo\n\nOf course that is bad when \"gitfoo\" _does_ exist, because the first line\nis mostly noise then. It does generally get covered up by man's pager,\nbut you may still see it after the pager exits (or immediately if you're\njust invoking a remote browser anyway).\n\nSo probably a bad idea.\n\n\nThe other thing it's tempting to do is teach \"git help\" to check the\nlist of recognized topics, like it checks the list of recognized\ncommands. I think that would work _mostly_ work, if we baked in the list\nat compile time based on what's in Documentation/. But it wouldn't\nautomatically pick up third-party topic manual pages. We pick up\nthird-party commands automatically by looking in the $PATH for them. But\nI don't think we can do the same for documentation (we'd have to search\n$MANPATH ourselves, which is bad enough, but of course it might be HTML\nor info pages; the user might not even have the manpages installed).\n\n-Peff\n"},{"id":"516368","messageId":"xmqqv7r1bnvx.fsf@gitster.g","threadId":"63308","inReplyTo":"20250418091612.GA10441@coredump.intra.peff.net","subject":"Re: Bug report: Minor glitch in \"git help\" error message","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2025-04-18T13:27:46Z","receivedAt":"2025-04-18T13:27:49Z","isPatch":false,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Jeff King writes:\n\n> ...\n> So probably a bad idea.\n> ...\n>\n> The other thing it's tempting to do is teach \"git help\" to check ...\n> ... We pick up\n> third-party commands automatically by looking in the $PATH for them. But\n> I don't think we can do the same for documentation ...\n\nGreat write-up. Thanks.\n\n\n"}]}