From: Tim Henigan <hidden> Date: 2016-06-15 22:47:43
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 <redacted>
---
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(-)
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 <redacted>
---
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.
From: Tim Henigan <hidden> Date: 2016-06-15 22:47:43
On Fri, Nov 13, 2009 at 5:19 PM, Nanako Shiraishi [off-list ref] 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
From: Junio C Hamano <hidden> Date: 2016-06-15 22:47:43
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=129424http://thread.gmane.org/gmane.comp.version-control.git/129906/focus=130646
From: Tim Henigan <hidden> Date: 2016-06-15 22:47:43
On Sun, Nov 15, 2009 at 4:08 AM, Junio C Hamano [off-list ref] 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.