| Message ID | CAAHpriMkqapiJuUGimn-i8SqcZmvmc=Wpk6oUr844uAkCYgMxA@mail.gmail.com (mailing list archive) |
|---|---|
| State | New |
| Headers | show |
| Series | Bug report: Minor glitch in "git help" error message | expand |
Keith Thompson <Keith.S.Thompson@gmail.com> writes: > What did you do before the bug happened? (Steps to reproduce your issue) > git help nosuchcommand > > What did you expect to happen? (Expected behavior) > An error message: "No manual entry for git-nosuchcommand" > > What happened instead? (Actual behavior) > An error message: "No manual entry for gitnosuchcommand" I am of two minds. When "git help" is asked for commands, your suggestion does make sense, i.e. $ git help dog-file No manual entry for gitdog-file And these two are moral equivalents. $ git help cat-file $ man git-cat-file But "git help" can ask for things other than subcommands. For example, these two are equivalents. $ git help glossary $ man gitglossary Notice the lack of "-" there? > If "nosuchcommand" were a git command, the man page would be > readable by typing "man git-nosuchcommand". The error message > should reflect that. (The error message is actually produced > by the "man" command.) In other words, if "nosuchguide" were a concept with guide, the man page is readable by "man gitnosuchguide", and the error message does reflect it. Unlike "git foo --help", where it is clear that the user expected a subommand "foo", when the user says "git help foo", we cannot tell whether the user asked for documentation for a command or a concept guide, so adding "-" there is a bit like robbing Peter to pay Paul. Thanks for a report.
On Thu, Apr 17, 2025 at 6:24 PM Junio C Hamano <gitster@pobox.com> wrote: > > Keith Thompson <Keith.S.Thompson@gmail.com> writes: > > > What did you do before the bug happened? (Steps to reproduce your issue) > > git help nosuchcommand > > > > What did you expect to happen? (Expected behavior) > > An error message: "No manual entry for git-nosuchcommand" > > > > What happened instead? (Actual behavior) > > An error message: "No manual entry for gitnosuchcommand" > > I am of two minds. When "git help" is asked for commands, your > suggestion does make sense, i.e. > > $ git help dog-file > No manual entry for gitdog-file > > And these two are moral equivalents. > > $ git help cat-file > $ man git-cat-file > > But "git help" can ask for things other than subcommands. > For example, these two are equivalents. > > $ git help glossary > $ man gitglossary > > Notice the lack of "-" there? Indeed. I've just learned several things that I either didn't know or had forgotten: * "git help foo" works for values of "foo" that aren't command names, like "glossary" or "cli". * "git help subcommand" directly invokes "man git-subcommand". * "git help topic" directly invokes "man gittopic". Clearly, "git help" knows whether the user wanted a subcommand or a topic if it's something that exists. If it isn't, "git help" has no way of knowing what was intended. Some proposed solutions, none of which I really like (except maybe the first): * Assume that the unrecognized word is a subcommand name. There will be errors (a message referring to "git-topic" that should have been "gittopic"), but I speculate that *most* (mistyped) arguments are command names. * Produce an error message like: "No such manual entry for git-foo or gitfoo" Problem: The error message comes directly from the "man" command, which can't be persuaded to produce the above message. Probably more effort than it's worth, and a potential new source of bugs. * Construct the man page names the same way for subcommands and topics, so "git help glossary" invokes "man git-glossary". This is a change to long-standing practice, and I don't expect this idea to be taken seriously. * Create aliases for all the topic names, so "git-glossary.7.gz" is a symlink to "gitglossary.7.gz". Likely too confusing, and not worthwhile for the sake of a one-character glitch in an error message. (Except that I might expect "man git-cli" to work, but I almost always use Git's help mechanism rather than "man".) > > > If "nosuchcommand" were a git command, the man page would be > > readable by typing "man git-nosuchcommand". The error message > > should reflect that. (The error message is actually produced > > by the "man" command.) > > In other words, if "nosuchguide" were a concept with guide, the man > page is readable by "man gitnosuchguide", and the error message does > reflect it. > > Unlike "git foo --help", where it is clear that the user expected a > subommand "foo", when the user says "git help foo", we cannot tell > whether the user asked for documentation for a command or a concept > guide, so adding "-" there is a bit like robbing Peter to pay Paul. > > Thanks for a report. > >
On Thu, Apr 17, 2025 at 08:52:10PM -0700, Keith Thompson wrote: > Some proposed solutions, none of which I really like (except maybe > the first): > > * Assume that the unrecognized word is a subcommand name. There will > be errors (a message referring to "git-topic" that should have been > "gittopic"), but I speculate that *most* (mistyped) arguments are > command names. I think the problem is that it's not unrecognized at all by Git. We don't have a list of topic pages, so we just assume any non-command is a topic, and hand if to "man". And it is "man" that realizes there is no such page. So you cannot assume up-front, as it would hand the wrong name to "man". But... > * Produce an error message like: > "No such manual entry for git-foo or gitfoo" > Problem: The error message comes directly from the "man" command, > which can't be persuaded to produce the above message. > Probably more effort than it's worth, and a potential new source > of bugs. We could detect a non-zero exit code from "man" and print more messages afterwards. Something like: $ git help foo No manual entry for gitfoo error: no command "git-foo" detected, and viewing the concept manual for "gitfoo" failed But I don't know how reliable that exit code is. In Debian's "man" implementation, code 16 is documented as "page not found". I'd expect most man implementations to at least return non-zero for that case. I would worry a bit about implementations which return non-zero even on success (e.g., if the roff formatter gets SIGPIPE when the pager closes early, would man ever propagate that code? If so, we'd get bogus error messages). The other complication is that "man" is not the only viewer. We might be showing HTML documentation with a browser, or even GNU info pages. And you're less likely to get a good exit code there (e.g., I'd expect most browser invocations to just remote-control an existing browser to open a new window/tab). I think the most accurate and foolproof thing is that "git help" could tell what it is doing as it works: it sees that "foo" is not a git command, so it decides to try it as the "gitfoo" topic page. It could say so: $ git help foo warning: no command "git-foo" found, assuming "foo" is a topic No manual entry for gitfoo Of course that is bad when "gitfoo" _does_ exist, because the first line is mostly noise then. It does generally get covered up by man's pager, but you may still see it after the pager exits (or immediately if you're just invoking a remote browser anyway). So probably a bad idea. The other thing it's tempting to do is teach "git help" to check the list of recognized topics, like it checks the list of recognized commands. I think that would work _mostly_ work, if we baked in the list at compile time based on what's in Documentation/. But it wouldn't automatically pick up third-party topic manual pages. We pick up third-party commands automatically by looking in the $PATH for them. But I don't think we can do the same for documentation (we'd have to search $MANPATH ourselves, which is bad enough, but of course it might be HTML or info pages; the user might not even have the manpages installed). -Peff
Jeff King <peff@peff.net> writes: > ... > So probably a bad idea. > ... > > The other thing it's tempting to do is teach "git help" to check ... > ... We pick up > third-party commands automatically by looking in the $PATH for them. But > I don't think we can do the same for documentation ... Great write-up. Thanks.
diff --git builtin/help.c builtin/help.c index c257079ceb..792549864f 100644 --- builtin/help.c +++ builtin/help.c @@ -450,7 +450,7 @@ static const char *cmd_to_page(const char *git_cmd) else if (!strcmp("scalar", git_cmd)) return xstrdup(git_cmd); else - return xstrfmt("git%s", git_cmd); + return xstrfmt("git-%s", git_cmd); } static void setup_man_path(void)
Thank you for filling out a Git bug report! Please answer the following questions to help us understand your issue. What did you do before the bug happened? (Steps to reproduce your issue) git help nosuchcommand What did you expect to happen? (Expected behavior) An error message: "No manual entry for git-nosuchcommand" What happened instead? (Actual behavior) An error message: "No manual entry for gitnosuchcommand" What's different between what you expected and what actually happened? The hyphen. If "nosuchcommand" were a git command, the man page would be readable by typing "man git-nosuchcommand". The error message should reflect that. (The error message is actually produced by the "man" command.) Anything else you want to add: Proposed patch (works on my system): ``` commit 148f2e07a7dbdbe72fa0bd4340b76cba12a19a24 (HEAD -> fix-help-bug) Author: Keith Thompson <Keith.S.Thompson@gmail.com> Date: 2025-04-17 15:35:44 -0700 Fix "git help" message for nonexistent subcommand ``` Please review the rest of the bug report below. You can delete any lines you don't wish to share. [System Info] git version: git version 2.49.0 cpu: x86_64 built from commit: 683c54c999c301c2cd6f715c411407c413b1d84e sizeof-long: 8 sizeof-size_t: 8 shell-path: /bin/sh libcurl: 8.5.0 OpenSSL: OpenSSL 3.0.13 30 Jan 2024 zlib: 1.3 uname: Linux 6.11.0-24-generic #24~24.04.1-Ubuntu SMP PREEMPT_DYNAMIC Tue Mar 25 20:14:34 UTC 2 x86_64 compiler info: gnuc: 13.3 libc info: glibc: 2.39 $SHELL (typically, interactive shell): /o/bin/bash [Enabled Hooks]