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

[Tim Henigan <tim.henigan@gmail.com>]

On Sun, Nov 15, 2009 at 4:08 AM, Junio C Hamano <gitster@pobox.com> wrote:
> 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?);

Sounds reasonable.


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

The usage string for "git remote update" should still be modified to match
the changes made to the man page in commit b344e161.  That commit
taught 'git remote update' to understand [group | remote].  The man page
was changed to document the new feature, but the usage string was not.

I will send v2 of this patch to make this change and add the author of
b344e161 (Finn Arne Gangstad) to the CC list to confirm.


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

Okay, I will look into this.  If I find a good solution, I will send
an RFC patch
that updates 'git remote add'.  Based on the email threads you cited below,
it sounds like the usage string for 'git push' is a good model to
follow.  If the
change looks sane, I will follow up with a patch series that updates each of
the 'git remote' subcommands.


> 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