Re: [PATCH] Add subcommand "help" to the list of most commonly used subcommands

[Teemu Likonen <tlikonen@iki.fi>]

Sverre Rabbelier wrote (2008-06-05 13:21 +0200):

> On Thu, Jun 5, 2008 at 12:32 PM, Johannes Schindelin
> <Johannes.Schindelin@gmx.de> wrote:
> > On Thu, 5 Jun 2008, Teemu Likonen wrote:
> >> Add subcommand "help" to the list of most commonly used subcommands
> >
> > Hrmpf.  IMO "help" is not really a _git_ command.  And I use it
> > really, really rarely.
> 
> I agree with this, but not because I don't use it rarely, but because
> there is no such command 'git-help'. I know that we are urging the
> user away from the dash notation, but if we want to advertise 'git
> help' as an actual command, at least make 'git' recognize it as an
> actual command instead of displaying the default usage notice (type
> 'git help' and see what I mean).

Well, you guys know the internals, I don't, but I have to admit that
your opinions sound weird to me at the moment. I mean, what's the
purpose of the command list printed after typing just "git"? To help
users, I'd say. Making help commands/options easily available is for the
same purpose. If manuals, mailing lists, web pages, IRC logs and your
grandmothers advertise "git help" as _the_ help command but at the same
time user can't find the command advertised in the git's own "metahelp"
page it's quite confusing.

I came up with this suggestion because of my personal confusion. Command
"git" speaks only about --help option and I was coming to a conclusion
that "git help" is deprecated and instructions are just out-of-date.
Then I read the "git help help" manual and saw that actually "git
--help" is internally converted to "git help" so it's probably not
deprecated (quite the opposite actually). And yet the front page printed
by "git" does not show it.

But ok, here's another suggestion: If "git help" is not a real git
command then maybe not list it with other commonly used commands.
Instead print separate instructions before or after the list. Something
like this:

  Type "git help <command>" for more information on a specific command
  or other topic.


Examples from other tools:

  $ hg help | grep help
   help         show help for a command, extension, or list of commands
  use "hg -v help" to show aliases and global options
  
  $ bzr help | grep help
    bzr help init      more help on e.g. init command
    bzr help commands  list all commands
    bzr help topics    list all help topics
  
  $ svn help | grep help
  Type 'svn help <subcommand>' for help on a specific subcommand.
     help (?, h)