git remote: Separate usage strings for subcommands

When the usage string for a subcommand must be printed, only print the information relevant to that command.

This commit also removes the options from the first line of the usage string (replacing them with '<options>' and lets them be documented in the paragraph below.

---

This patch is based on:
http://article.gmane.org/gmane.comp.version-control.git/132953

All usage strings are still only located at the top of file. However, separate usage string arrays have been created for each subcommand.

v2 fixed line wrap issues present in v1.

v3 changes include:
- Changed usage strings to use '<options>...' rather than document the options both in the actual string and in the OPT_x array (as recommended by Junio).
- Removed the change made to the usage string array constructed in 'cmd_remote'. v2 was broken because that change had made the command stop recognizing the '-v' option. Added an extra note here which explains that '-v' is only valid when placed after 'git remote' and before any 'subcommand'.
- Updated the man page.

v4 changes include:
- Changed usage strings to use '<options>' rather than '<options>...' based on feedback from Jonathan Nieder. See [1] for details.
- Corrected "git remote set-head" usage string to show the required [-a | -d | <branch>] portion of the command.
- Corrected "git remote update" usage string to show the optional, but not otherwise documented [<group> | <remote>] portion of the command.
- Removed 2 more instances of "<subcommand> specific options".

[1] http://thread.gmane.org/gmane.comp.version-control.git/133151/focus=133160

 Documentation/git-remote.txt |   13 +++++----
 builtin-remote.c             |   60 +++++++++++++++++++++++++----------------
 2 files changed, 43 insertions(+), 30 deletions(-)

index 82a3d29..ee3dc80 100644
@@ -9,14 +9,14 @@ git-remote - manage set of tracked repositories
 SYNOPSIS
 --------
 [verse]
-'git remote' [-v | --verbose]
-'git remote add' [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>
+'git remote' [<options>]
+'git remote add' [<options>] <name> <url>
 'git remote rename' <old> <new>
 'git remote rm' <name>
-'git remote set-head' <name> [-a | -d | <branch>]
-'git remote show' [-n] <name>
-'git remote prune' [-n | --dry-run] <name>
-'git remote update' [-p | --prune] [group | remote]...
+'git remote set-head' <name> [<options>] [-a | -d | <branch>]
+'git remote show' [<options>] <name>
+'git remote prune' [<options>] <name>
+'git remote update' [<options>] [<group> | <remote>]...
 
 DESCRIPTION
 -----------

@@ -30,6 +30,7 @@ OPTIONS
 -v::
 --verbose::
 	Be a little more verbose and show remote url after name.
+	NOTE: This must be placed between `remote` and `subcommand`.
 
 
 COMMANDS

1.6.5.2.186.ga4d60

Quoting Tim Henigan <[email protected]>

I think this is a huge improvement.

... snip ...

The original version of this patch [1] left the contents of the usage strings intact. However, Junio expressed a preference to change them to use the generic <options>. See this thread for the discussion [2].

[1] http://article.gmane.org/gmane.comp.version-control.git/133048/
[2] http://thread.gmane.org/gmane.comp.version-control.git/132968/focus=133050

Sorry, but I think you misunderstood what I meant, then. in [2], I said...

I am not sure about the value of reusing option string like this, and for

Here, please note that I was objecting to the use of _the same string_ in both contexts ("reusing").

all other subcommands the same comment applies. For example, in the case of "remote add -h", you would use

"git remote add [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>"

from REMOTE_ADD_USAGE, but ...

> ... hunk to give the builtin_remote_add_usage[] that uses the same > ... REMOTE_ADD_USAGE to parse_options()

... the options list is used to reproduce the information in a major part of that string already. So I would prefer builtin_remote_add_usage[] to be something like:

"git remote add [<options>...] <name> <url>"

I meant that we want to change "remote add -h" to show this here; and the reason why I doubted "the value of reusing option string" was because I wanted to do so without touching the concise list of the subcommands and their options given by "remote -h". Otherwise, it would have made perfect sense to use preprocessor macros to share the two identical strings.

In your response to my above comment, you indicated that you wanted to do the [<options>] thing as a separate patch (your original patch spelled options in full). I took it to mean that you would do that only for the subcommand help, and did not respond, because

(1) doing that to the subcommand help would be a good idea anyway; and

(2) you will realize what I said in the message about "the value of reusing option string" was correct when you see the end result, which will regress "remote -h" output.

In this case, unfortunately (2) didn't happen before Nana pointed it out.

... snip ...

Okay, I believe I understand now, but let's test that theory ;)

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,
Tim

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.