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

From: Scott Chacon <schacon@gmail.com>
Date: Dec 2, 2008, 23:39 UTC
Message-ID: <d411cc4a0812021539g34d3a94bn7e873f8cf04adc56@mail.gmail.com>
In-Reply-To: <20081202233004.GA22379@coredump.intra.peff.net>

Hi,

On Tue, Dec 2, 2008 at 3:30 PM, Jeff King <peff@peff.net> wrote:

Show 14 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've always felt it was helpful to newcomers to have that page there with the couple dozen commands you might use - mostly in case you've forgotten what the exact command name was. Hg does something like 'hg help' which gives you more commands, but I feel like just having the quick cheat-sheet is generally really helpful. If someone just wants to remember what the command 'checkout' was, I wouldn't want them to have to go to two places - one to look up what the task document was and then another to view that.

My $0.02

Show 5 quoted lines

> I think there has been mention of task-oriented documentation pointers
> before, and I think this is a place where we would want it.
>
> -Peff
>

Scott