From: Junio C Hamano <gitster@pobox.com>
Date: Fri, 20 Nov 2009 09:36:46 GMT
Subject: Re: [PATCH v4] git remote: Separate usage strings for subcommands
Message-ID: <7vskc95yhd.fsf@alter.siamese.dyndns.org>
In-Reply-To: <32c343770911191058x7be7d34ascc3564064b880213@mail.gmail.com>

Tim Henigan <tim.henigan@gmail.com> writes:

> Using the 'add' subcommand as an example, the desired output is:
>
> Output of 'git remote -h':
>     "git remote [-v | --verbose]"
>     "git remote add [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>"
>     etc.
>
> Output of 'git remote add -h':
>     "git remote add [<options>...] <name> <url>"
>     followed by the detailed description given by 'parse_options()'.
>
> Text in 'man git-remote':
>     "git remote add [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>"
>     with the options explained in detail later in the file.
>
> Thanks for your patience,

I think the above looks good; thank _you_ for your patience.

I often wonder if we want to add to the parse-options library a function
that takes a "const struct option *" and some other unspecified hints, and
fills a strbuf with a one-line description, e.g.

    "[-t <branch>] [-m <master>] [-f] [--mirror]"

I expect we would eventually want to handle something like (this example
is from "git push"):

    "[--all | --mirror | --tags] [-n | --dry-run]"

and walking elements in a "struct option" one by one wouldn't give us
enough information to group all/mirror/tags in "one of these" brackets,
and that is what I mean by "some other unspecified hints".  Obviously we
could do the "[-n|--dry-run]" with existing information.

A helper function like that may make things a bit easier.  parse_options()
may need to take a custom callback function of some sort so that you can
override what parse_options_usage() does when responding to "remote -h"
and generate the list of subcommands and their options on the fly, though.

But that is all outside the scope of this particular patch.