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

From: Teemu Likonen <tlikonen@iki.fi>
Date: Jun 5, 2008, 13:22 UTC
Message-ID: <20080605132257.GA30995@mithlond.arda.local>
In-Reply-To: <bd6139dc0806050421l3a242a98sdfa51248b380badc@mail.gmail.com>

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

Show 14 quoted lines

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