Re: [PATCH] Update 'git remote' usage and man page to match.

Tim Henigan [off-list ref] writes:

On Fri, Nov 13, 2009 at 5:19 PM, Nanako Shiraishi [off-list ref] wrote:

quoted

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