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

From: Keith Thompson <keith.s.thompson@gmail.com>
Date: Apr 18, 2025, 03:52 UTC
Message-ID: <CAAHpriNYikDFwiTpjZEupG4yWOkbzW5DnBcsUnBKkfxxxtWNkw@mail.gmail.com>
In-Reply-To: <xmqq5xj2clcx.fsf@gitster.g>

On Thu, Apr 17, 2025 at 6:24 PM Junio C Hamano <gitster@pobox.com> wrote:

Show 30 quoted lines

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

Show 18 quoted lines

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