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

From: Tim Henigan <tim.henigan@gmail.com>
Date: Nov 15, 2009, 19:29 UTC
Message-ID: <32c343770911151129q7e2d9960q29205118c54abf4a@mail.gmail.com>
In-Reply-To: <7vr5s0qhnp.fsf@alter.siamese.dyndns.org>

On Sun, Nov 15, 2009 at 4:08 AM, Junio C Hamano <gitster@pobox.com> wrote:

Show 29 quoted lines

> 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.

Show 5 quoted lines

> 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