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

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

[Keith Thompson]

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

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)
```

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]

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

[Junio C Hamano]

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.

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

[Keith Thompson]

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

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

[Jeff King]

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

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

[Junio C Hamano]

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.