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

From: Junio C Hamano <gitster@pobox.com>
Date: Dec 3, 2008, 00:10 UTC
Message-ID: <7vfxl6m84g.fsf@gitster.siamese.dyndns.org>
In-Reply-To: <20081202233004.GA22379@coredump.intra.peff.net>

Jeff King <peff@peff.net> writes:

Show 17 quoted lines

> On Tue, Dec 02, 2008 at 11:55:03PM +0100, Johannes Schindelin wrote:
>
>> If the whole thing gets longer than 24 lines, we have to leave some things 
>> out.  Personally, I consider rm and mv unimportant enough that they could 
>> be shown in an extended list, but be left out of the summary page.
>
> For the record, the current output is 26 lines, plus you probably want
> to account for 1 line of the user's next shell prompt. So we are 3 lines
> over already.
>
> Scott's proposal is about grouping the commands more sensibly. Many of
> the complaints are about the length of the output. Maybe we should scrap
> having a list of commands altogether and just point at section-specific
> documentation, each of which could discuss basic commands related to it.
>
> I think there has been mention of task-oriented documentation pointers
> before, and I think this is a place where we would want it.

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

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 the git-diff(1) manual page. If you pick one of the headings, say, "Basic", you may get a more extended description of commands in the category, that may include other basic commands not in the front page, perhaps, like this:

    (review)
    diff HEAD: view what you did since the last commit
    diff: view what you did since you last added
    diff --cached: view what you already added
    status: list what are added and changes yet to be added

    (undo)
    checkout path...: checkout a copy from the staging area
    checkout HEAD path...: checkout a copy from the last commit
    reset: undo earlier "git add" to the staging area
    reset path...: do so only for the named paths

    (record)
    mv path1 path2: move the state of path1 to path2
    rm path2: remove path2
    rm --cached path2: do so without losing the copy in the working tree
    add: add the contents to the staging area
    add -p: do so interactively, hunk by hunk
    commit: record the changes you added to the staging area
    commit path...: record all the changes to the paths, ignoring
    	changes you added to the staging area for other paths.

and again each element can be a "link".