From: Junio C Hamano <gitster@pobox.com>
Date: Sun, 15 Nov 2009 09:08:42 GMT
Subject: Re: [PATCH] Update 'git remote' usage and man page to match.
Message-ID: <7vr5s0qhnp.fsf@alter.siamese.dyndns.org>
In-Reply-To: <32c343770911142034j6cf10e36jbd031c49119973c8@mail.gmail.com>

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

> 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