[RFC] Another way to provide help details. (was Re: [PATCH] Add help details to git help command.)

From: Steven Cole <elenstev@mesatop.com>
Date: Apr 19, 2005, 01:40 UTC
Message-ID: <200504181940.54453.elenstev@mesatop.com>
In-Reply-To: <4263E782.6040608@mesatop.com>

On Monday 18 April 2005 10:59 am, Steven Cole wrote:

Show 16 quoted lines

> Petr Baudis wrote:
> > Dear diary, on Mon, Apr 18, 2005 at 06:42:26AM CEST, I got a letter
> > where Steven Cole <elenstev@mesatop.com> told me that...
> [snippage]
> > 
> >>This patch will provide the comment lines in the shell script associated
> >>with the command, cleaned up a bit for presentation.
> >>
> >>BUGS: This will also print any comments in the entire file, which may
> >>not be desired.  If a command name and shell script filename
> >>do not follow the usual convention, this won't work, e.g. ci for commit.
> > 
> > 
> > Hey, those BUGS are the only slightly non-trivial thing on the whole
> > thing! I could do this patch myself... ;-) Also, you don't want to print
> > the first newline and the Copyright notices.

Here is perhaps a better way to provide detailed help for each git command. A command.help file for each command can be written in the style of a man page.

The modfication to the main git script will be trivial. Here are the two commands I've done so far.

What do folks think about this approach?

Steven

[steven@spc git-pasky]$ ./git help add
NAME
        add - Add new file or files to a GIT repository.

SYNOPSIS
        add FILE...

DESCRIPTION
        Takes a list of file names at the command line, and schedules them
        for addition to the GIT repository at the next commit.

AUTHOR
        Written by Petr Baudis.

REPORTING BUGS
        Report bugs to <git@vger.kernel.org>

COPYRIGHT
        Copyright (c) Petr Baudis, 2005

BUGS
        Those files are omitted from show-diff output!

SEE ALSO
        The source code for this command is gitadd.sh.

[steven@spc git-pasky]$ ./git help addremote
NAME
        addremote -  Add new "remote" to the GIT repository.

SYNOPSIS
        addremote RNAME RSYNC_URL

DESCRIPTION
        Takes the remote's name and rsync URL.

        After you add a remote, you can "git pull" it whenever you want
        and it will keep your dircache in sync with it. Its latest commit
        is accessible as .git/heads/remotename (or - more conveniently -
        as $(commit-id remotename)). For example, to make a diff between
        Linus (after you added him) and your current tree, do

        git pull linus
        git diff $(commit-id linus)

AUTHOR
        Written by Petr Baudis.

REPORTING BUGS
        Report bugs to <git@vger.kernel.org>

COPYRIGHT
        Copyright (c) Petr Baudis, 2005

TODO
        gitdiff.sh et al should accept remote names as ids.

SEE ALSO
        The source code for this command is gitaddremote.sh.