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

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

[Tim Henigan]

This commit:

1) Removes documentation of '--verbose' from the synopsis portion
of the usage string since it is a general option.

2) Removes the 'remote' option from 'git remote update' in the
man page.  This option had already been removed from the usage
string in the code, but the man page was not updated to match.

Signed-off-by: Tim Henigan <tim.henigan@gmail.com>
---

This is a resend of the patch at:
http://article.gmane.org/gmane.comp.version-control.git/132732

I forgot to include 'gitster at pobox dot com' on the original patch.
No changes were made to the patch itself.

Sorry for the noise.

 Documentation/git-remote.txt |    4 ++--
 builtin-remote.c             |    4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 82a3d29..32ff95b 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -9,14 +9,14 @@ git-remote - manage set of tracked repositories
 SYNOPSIS
 --------
 [verse]
-'git remote' [-v | --verbose]
+'git remote'
 'git remote add' [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>
 'git remote rename' <old> <new>
 'git remote rm' <name>
 'git remote set-head' <name> [-a | -d | <branch>]
 'git remote show' [-n] <name>
 'git remote prune' [-n | --dry-run] <name>
-'git remote update' [-p | --prune] [group | remote]...
+'git remote update' [-p | --prune] [group]...

 DESCRIPTION
 -----------
diff --git a/builtin-remote.c b/builtin-remote.c
index 0777dd7..3756e91 100644
--- a/builtin-remote.c
+++ b/builtin-remote.c
@@ -8,14 +8,14 @@
 #include "refs.h"

 static const char * const builtin_remote_usage[] = {
-	"git remote [-v | --verbose]",
+	"git remote",
 	"git remote add [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>",
 	"git remote rename <old> <new>",
 	"git remote rm <name>",
 	"git remote set-head <name> [-a | -d | <branch>]",
 	"git remote show [-n] <name>",
 	"git remote prune [-n | --dry-run] <name>",
-	"git remote [-v | --verbose] update [-p | --prune] [group]",
+	"git remote update [-p | --prune] [group]",
 	NULL
 };

-- 
1.6.5.2.180.gc5b3e.dirty

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

[Nanako Shiraishi]

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

> This commit:
>
> 1) Removes documentation of '--verbose' from the synopsis portion
> of the usage string since it is a general option.
>
> 2) Removes the 'remote' option from 'git remote update' in the
> man page.  This option had already been removed from the usage
> string in the code, but the man page was not updated to match.
>
> Signed-off-by: Tim Henigan <tim.henigan@gmail.com>
> ---

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.

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

[Tim Henigan]

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.

Thank for reviewing,
Tim

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

[Junio C Hamano]

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

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

[Tim Henigan]

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

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

[Tim Henigan]

This commit:

1) Removes documentation of '--verbose' from the synopsis portion
of the usage string since it is a general option.

2) Removes the 'remote' option from 'git remote update' in the
man page.  This option had already been removed from the usage
string in the code, but the man page was not updated to match.

Signed-off-by: Tim Henigan <tim.henigan@gmail.com>
---

 Documentation/git-remote.txt |    4 ++--
 builtin-remote.c             |    4 ++--
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt
index 82a3d29..32ff95b 100644
--- a/Documentation/git-remote.txt
+++ b/Documentation/git-remote.txt
@@ -9,14 +9,14 @@ git-remote - manage set of tracked repositories
 SYNOPSIS
 --------
 [verse]
-'git remote' [-v | --verbose]
+'git remote'
 'git remote add' [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>
 'git remote rename' <old> <new>
 'git remote rm' <name>
 'git remote set-head' <name> [-a | -d | <branch>]
 'git remote show' [-n] <name>
 'git remote prune' [-n | --dry-run] <name>
-'git remote update' [-p | --prune] [group | remote]...
+'git remote update' [-p | --prune] [group]...

 DESCRIPTION
 -----------
diff --git a/builtin-remote.c b/builtin-remote.c
index 0777dd7..3756e91 100644
--- a/builtin-remote.c
+++ b/builtin-remote.c
@@ -8,14 +8,14 @@
 #include "refs.h"

 static const char * const builtin_remote_usage[] = {
-	"git remote [-v | --verbose]",
+	"git remote",
 	"git remote add [-t <branch>] [-m <master>] [-f] [--mirror] <name> <url>",
 	"git remote rename <old> <new>",
 	"git remote rm <name>",
 	"git remote set-head <name> [-a | -d | <branch>]",
 	"git remote show [-n] <name>",
 	"git remote prune [-n | --dry-run] <name>",
-	"git remote [-v | --verbose] update [-p | --prune] [group]",
+	"git remote update [-p | --prune] [group]",
 	NULL
 };

-- 
1.6.5.2.180.gc5b3e.dirty