{"thread":{"id":"21601","subject":"[PATCH] Update 'git remote' usage and man page to match.","startedAt":"2009-11-13T01:15:34Z","lastAt":"2009-11-15T19:29:17Z","messageCount":5,"participants":["Tim Henigan","Nanako Shiraishi","Junio C Hamano"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"127487","messageId":"32c343770911121715l7507b2d5j8c6cf8cccd1f1a61@mail.gmail.com","threadId":"21601","inReplyTo":null,"subject":"[PATCH] Update 'git remote' usage and man page to match.","fromName":"Tim Henigan","fromEmail":"tim.henigan@gmail.com","sentAt":"2009-11-13T01:15:34Z","receivedAt":"2009-11-13T01:15:34Z","isPatch":true,"sender":{"key":"tim.henigan@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42022?v=4"},"body":"This commit:\n\n1) Removes documentation of '--verbose' from the synopsis portion\nof the usage string since it is a general option.\n\n2) Removes the 'remote' option from 'git remote update' in the\nman page. This option had already been removed from the usage\nstring in the code, but the man page was not updated to match.\n\nSigned-off-by: Tim Henigan \n---\n\nThis is a resend of the patch at:\nhttp://article.gmane.org/gmane.comp.version-control.git/132732\n\nI forgot to include 'gitster at pobox dot com' on the original patch.\nNo changes were made to the patch itself.\n\nSorry for the noise.\n\n Documentation/git-remote.txt | 4 ++--\n builtin-remote.c | 4 ++--\n 2 files changed, 4 insertions(+), 4 deletions(-)\n\ndiff --git a/Documentation/git-remote.txt b/Documentation/git-remote.txt\nindex 82a3d29..32ff95b 100644\n--- a/Documentation/git-remote.txt\n+++ b/Documentation/git-remote.txt\n@@ -9,14 +9,14 @@ git-remote - manage set of tracked repositories\n SYNOPSIS\n --------\n [verse]\n-'git remote' [-v | --verbose]\n+'git remote'\n 'git remote add' [-t ] [-m ] [-f] [--mirror] \n 'git remote rename' \n 'git remote rm' \n 'git remote set-head' [-a | -d | ]\n 'git remote show' [-n] \n 'git remote prune' [-n | --dry-run] \n-'git remote update' [-p | --prune] [group | remote]...\n+'git remote update' [-p | --prune] [group]...\n\n DESCRIPTION\n -----------\ndiff --git a/builtin-remote.c b/builtin-remote.c\nindex 0777dd7..3756e91 100644\n--- a/builtin-remote.c\n+++ b/builtin-remote.c\n@@ -8,14 +8,14 @@\n #include \"refs.h\"\n\n static const char * const builtin_remote_usage[] = {\n-\t\"git remote [-v | --verbose]\",\n+\t\"git remote\",\n \t\"git remote add [-t ] [-m ] [-f] [--mirror] \",\n \t\"git remote rename \",\n \t\"git remote rm \",\n \t\"git remote set-head [-a | -d | ]\",\n \t\"git remote show [-n] \",\n \t\"git remote prune [-n | --dry-run] \",\n-\t\"git remote [-v | --verbose] update [-p | --prune] [group]\",\n+\t\"git remote update [-p | --prune] [group]\",\n \tNULL\n };\n\n-- \n1.6.5.2.180.gc5b3e.dirty\n"},{"id":"127520","messageId":"20091114071948.6117@nanako3.lavabit.com","threadId":"21601","inReplyTo":"32c343770911121715l7507b2d5j8c6cf8cccd1f1a61@mail.gmail.com","subject":"Re: [PATCH] Update 'git remote' usage and man page to match.","fromName":"Nanako Shiraishi","fromEmail":"nanako3@lavabit.com","sentAt":"2009-11-13T22:19:48Z","receivedAt":"2009-11-13T22:19:48Z","isPatch":true,"sender":{"key":"nanako3@lavabit.com","avatar":"https://gravatar.com/avatar/3777b9e201c5883a62b1a6fdf7c53f2d712d1d80989146063ea861e33aad72a8?d=mp&s=160"},"body":"Quoting Tim Henigan writes:\n\n> This commit:\n>\n> 1) Removes documentation of '--verbose' from the synopsis portion\n> of the usage string since it is a general option.\n>\n> 2) Removes the 'remote' option from 'git remote update' in the\n> man page. This option had already been removed from the usage\n> string in the code, but the man page was not updated to match.\n>\n> Signed-off-by: Tim Henigan \n> ---\n\nThe second change is good but why do you remove -v from the \nsynopsis section? Why is it a good idea? Manual pages for \nmany other commands list --verbose in their synopsis section.\n"},{"id":"127581","messageId":"32c343770911142034j6cf10e36jbd031c49119973c8@mail.gmail.com","threadId":"21601","inReplyTo":"20091114071948.6117@nanako3.lavabit.com","subject":"Re: [PATCH] Update 'git remote' usage and man page to match.","fromName":"Tim Henigan","fromEmail":"tim.henigan@gmail.com","sentAt":"2009-11-15T04:34:00Z","receivedAt":"2009-11-15T04:34:00Z","isPatch":true,"sender":{"key":"tim.henigan@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42022?v=4"},"body":"On Fri, Nov 13, 2009 at 5:19 PM, Nanako Shiraishi wrote:\n>\n> The second change is good but why do you remove -v from the\n> synopsis section? Why is it a good idea? Manual pages for\n> many other commands list --verbose in their synopsis section.\n>\n\nAfter checking other git operations (fetch, pull, clone, commit, merge, etc)\nI found that none of these other commands document '-v' in the synopsis.\n\nWith that in mind, I wondered why it had been listed for 'git remote'. My best\nguess is that only some of the 'git remote' subcommands are affected by '-v'.\nHowever, to me it still seems better to only mention it as a general option.\nThat way if subcommands add/remote support for '-v', the usage string\nand man page don't need to be updated.\n\nPlease note that even with the change, '-v' is still printed as one of the\ngeneral options in the usage string. I simply removed it from the synopsis\nsection.\n\nThank for reviewing,\nTim\n"},{"id":"127592","messageId":"7vr5s0qhnp.fsf@alter.siamese.dyndns.org","threadId":"21601","inReplyTo":"32c343770911142034j6cf10e36jbd031c49119973c8@mail.gmail.com","subject":"Re: [PATCH] Update 'git remote' usage and man page to match.","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2009-11-15T09:08:42Z","receivedAt":"2009-11-15T09:08:42Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Tim Henigan writes:\n\n> On Fri, Nov 13, 2009 at 5:19 PM, Nanako Shiraishi wrote:\n>>\n>> The second change is good but why do you remove -v from the\n>> synopsis section? Why is it a good idea? Manual pages for\n>> many other commands list --verbose in their synopsis section.\n>>\n>\n> After checking other git operations (fetch, pull, clone, commit, merge, etc)\n> I found that none of these other commands document '-v' in the synopsis.\n>\n> With that in mind, I wondered why it had been listed for 'git remote'. My best\n> guess is that only some of the 'git remote' subcommands are affected by '-v'.\n> However, to me it still seems better to only mention it as a general option.\n> That way if subcommands add/remote support for '-v', the usage string\n> and man page don't need to be updated.\n>\n> Please note that even with the change, '-v' is still printed as one of the\n> general options in the usage string. I simply removed it from the synopsis\n> section.\n\nYou noticed a good issue to address. That is, \"git remote -h\" output\nlooks Ok but \"git remote add -h\" and friends show way suboptimal help.\nThe current output looks like:\n\n $ git remote add -h\n usage: git remote [-v | --verbose]\n or: git remote add [-t ] [-m ] [-f] [--mirror] \n \n or: git remote rename \n or: git remote rm \n or: git remote set-head [-a | -d | ]\n or: git remote show [-n] \n or: git remote prune [-n | --dry-run] \n or: git remote [-v | --verbose] update [-p | --prune] [group]\n\n add specific options\n -f, --fetch fetch the remote branches\n -t, --track branch(es) to track\n -m, --master \n master branch\n --mirror no separate remotes\n\nAs the user already knows \"add\" is the subcommand she is interested in,\nthis is insane.\n\nMy preference is:\n\n (1) to drop your change to the synopsis section (\"git remote -v\" is a\n valid way to get more verbose information, isn't it?);\n\n (2) to keep the current output of \"git remote -h\";\n\n (3) to drop the general description section altogether from \"git remote\n add -h\" output;\n\nI think this is related to a bigger issue of how we generally would want\nto show help in response to \"-h\", and also in the manual pages.\n\n http://thread.gmane.org/gmane.comp.version-control.git/129399/focus=129424\n http://thread.gmane.org/gmane.comp.version-control.git/129906/focus=130646\n"},{"id":"127626","messageId":"32c343770911151129q7e2d9960q29205118c54abf4a@mail.gmail.com","threadId":"21601","inReplyTo":"7vr5s0qhnp.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Update 'git remote' usage and man page to match.","fromName":"Tim Henigan","fromEmail":"tim.henigan@gmail.com","sentAt":"2009-11-15T19:29:17Z","receivedAt":"2009-11-15T19:29:17Z","isPatch":true,"sender":{"key":"tim.henigan@gmail.com","avatar":"https://avatars.githubusercontent.com/u/42022?v=4"},"body":"On Sun, Nov 15, 2009 at 4:08 AM, Junio C Hamano wrote:\n> You noticed a good issue to address.  That is, \"git remote -h\" output\n> looks Ok but \"git remote add -h\" and friends show way suboptimal help.\n> The current output looks like:\n>\n>    $ git remote add -h\n>    usage: git remote [-v | --verbose]\n>       or: git remote add [-t ] [-m ] [-f] [--mirror] \n>       \n>       or: git remote rename \n>       or: git remote rm \n>       or: git remote set-head [-a | -d | ]\n>       or: git remote show [-n] \n>       or: git remote prune [-n | --dry-run] \n>       or: git remote [-v | --verbose] update [-p | --prune] [group]\n>\n>    add specific options\n>        -f, --fetch           fetch the remote branches\n>        -t, --track  branch(es) to track\n>        -m, --master \n>                              master branch\n>        --mirror              no separate remotes\n>\n> As the user already knows \"add\" is the subcommand she is interested in,\n> this is insane.\n>\n> My preference is:\n>\n>  (1) to drop your change to the synopsis section (\"git remote -v\" is a\n>     valid way to get more verbose information, isn't it?);\n\nSounds reasonable.\n\n\n>  (2) to keep the current output of \"git remote -h\";\n\nThe usage string for \"git remote update\" should still be modified to match\nthe changes made to the man page in commit b344e161. That commit\ntaught 'git remote update' to understand [group | remote]. The man page\nwas changed to document the new feature, but the usage string was not.\n\nI will send v2 of this patch to make this change and add the author of\nb344e161 (Finn Arne Gangstad) to the CC list to confirm.\n\n\n>  (3) to drop the general description section altogether from \"git remote\n>     add -h\" output;\n\nOkay, I will look into this. If I find a good solution, I will send\nan RFC patch\nthat updates 'git remote add'. Based on the email threads you cited below,\nit sounds like the usage string for 'git push' is a good model to\nfollow. If the\nchange looks sane, I will follow up with a patch series that updates each of\nthe 'git remote' subcommands.\n\n\n> I think this is related to a bigger issue of how we generally would want\n> to show help in response to \"-h\", and also in the manual pages.\n>\n>  http://thread.gmane.org/gmane.comp.version-control.git/129399/focus=129424\n>  http://thread.gmane.org/gmane.comp.version-control.git/129906/focus=130646\n"}]}