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

quoted text
> On Fri, Nov 13, 2009 at 5:19 PM, Nanako Shiraishi <nanako3@lavabit.com> wrote:
>>
>> The second change is good but why do you remove -v from the
>> synopsis section? Why is it a good idea? Manual pages for
>> many other commands list --verbose in their synopsis section.
>>
>
> After checking other git operations (fetch, pull, clone, commit, merge, etc)
> I found that none of these other commands document '-v' in the synopsis.
>
> With that in mind, I wondered why it had been listed for 'git remote'.  My best
> guess is that only some of the 'git remote' subcommands are affected by '-v'.
> However, to me it still seems better to only mention it as a general option.
> That way if subcommands add/remote support for '-v', the usage string
> and man page don't need to be updated.
>
> Please note that even with the change, '-v' is still printed as one of the
> general options in the usage string.  I simply removed it from the synopsis
> section.

You noticed a good issue to address.  That is, "git remote -h" output
looks Ok but "git remote add -h" and friends show way suboptimal help.
The current output looks like:

    $ git remote add -h
    usage: git remote [-v | --verbose]
       or: git remote add [-t <branch>] [-m <master>] [-f] [--mirror] <name>
       <url>
       or: git remote rename <old> <new>
       or: git remote rm <name>
       or: git remote set-head <name> [-a | -d | <branch>]
       or: git remote show [-n] <name>
       or: git remote prune [-n | --dry-run] <name>
       or: git remote [-v | --verbose] update [-p | --prune] [group]

    add specific options
        -f, --fetch           fetch the remote branches
        -t, --track <branch>  branch(es) to track
        -m, --master <branch>
                              master branch
        --mirror              no separate remotes

As the user already knows "add" is the subcommand she is interested in,
this is insane.

My preference is:

 (1) to drop your change to the synopsis section ("git remote -v" is a
     valid way to get more verbose information, isn't it?);

 (2) to keep the current output of "git remote -h";

 (3) to drop the general description section altogether from "git remote
     add -h" output;

I think this is related to a bigger issue of how we generally would want
to show help in response to "-h", and also in the manual pages.

  http://thread.gmane.org/gmane.comp.version-control.git/129399/focus=129424
  http://thread.gmane.org/gmane.comp.version-control.git/129906/focus=130646
--
To unsubscribe from this list: send the line "unsubscribe git" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html