Re: Bug report: Minor glitch in "git help" error message

From: Jeff King <peff@peff.net>
Date: Apr 18, 2025, 09:16 UTC
Message-ID: <20250418091612.GA10441@coredump.intra.peff.net>
In-Reply-To: <CAAHpriNYikDFwiTpjZEupG4yWOkbzW5DnBcsUnBKkfxxxtWNkw@mail.gmail.com>

On Thu, Apr 17, 2025 at 08:52:10PM -0700, Keith Thompson wrote:

Show 7 quoted lines

> 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...

Show 6 quoted lines

> * 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