Tim Henigan <tim.henigan@xxxxxxxxx> writes:
> On Fri, Nov 13, 2009 at 5:19 PM, Nanako Shiraishi <nanako3@xxxxxxxxxxx> 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@xxxxxxxxxxxxxxx
More majordomo info at http://vger.kernel.org/majordomo-info.html