Re: [PATCH] Modified the default git help message to be grouped by topic

From: Jeff King <peff@peff.net>
Date: Dec 3, 2008, 00:37 UTC
Message-ID: <20081203003731.GA23780@coredump.intra.peff.net>
In-Reply-To: <7vfxl6m84g.fsf@gitster.siamese.dyndns.org>

On Tue, Dec 02, 2008 at 04:10:07PM -0800, Junio C Hamano wrote:

Show 14 quoted lines

> It might not be a bad idea to make this "top page help" into an
> interactive hierarchical help topic browser.  You would start a page that
> might look like this:
> 
>     Bootstrapping -- preparing an area to work in
>         init, clone
>     Basic -- review, undo and record your changes
>         diff, status, checkout <path>, add, reset, commit
>     History -- inspect what you have now, and what happened before
>         log, blame, grep, show
>     Branching and Merging -- build and use alternate histories
> 	branch, checkout -b, merge, rebase
>     Working with Others
> 	remote, fetch, pull, push

Yes, that is the sort of thing I was thinking of. And I think your layout addresses Scott's concern, which is to keep names of commands available for quick reference. So really we are ditching the descriptions.

> with each of the command and the heading being a "link" (use ncurses for
> that).  If you choose the leaf-level command (say, 'diff'), you will get

I'm not sure we need anything so fancy. I was thinking of something like:

  Bootstrapping -- preparing an area to work in (bootstrapping)
    init, clone
  ...
  Working with Others (others)
    remote, fetch, pull, push

  Use "git help <subject>" for more help on one of these subjects, or
  "git help <command>" for help with a specific command.

And maybe the "(bootstrapping)" could be typographically more obvious as the subject keyword, but I think you get the point (and for "Bootstrapping", it's obvious what the keyword would be, but for "Working with Others" it's not).

And obviously something with ncurses would save you typing, but I have no desire to recreate "info" or "lynx" here (and I also think that "git" or "git foo" displaying help should remain non-interactive to cause the least surprise).

-Peff