{"thread":{"id":"35137","subject":"[PATCH] rev-parse doc: clarify use of optional / required arguments","startedAt":"2013-10-14T14:23:31Z","lastAt":"2013-10-15T10:49:45Z","messageCount":5,"participants":["Nicolas Vigier","Jonathan Nieder","brian m. carlson"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"228929","messageId":"1381760611-9573-1-git-send-email-boklm@mars-attacks.org","threadId":"35137","inReplyTo":null,"subject":"[PATCH] rev-parse doc: clarify use of optional / required arguments","fromName":"Nicolas Vigier","fromEmail":"boklm@mars-attacks.org","sentAt":"2013-10-14T14:23:31Z","receivedAt":"2013-10-14T14:23:31Z","isPatch":true,"sender":{"key":"boklm@mars-attacks.org","avatar":"https://avatars.githubusercontent.com/u/405910?v=4"},"body":"\"the option is optional\" was confusing as it is not the option but its\nargument which is optional.\n\nSigned-off-by: Nicolas Vigier \n---\n Documentation/git-rev-parse.txt | 5 +++--\n 1 file changed, 3 insertions(+), 2 deletions(-)\n\ndiff --git a/Documentation/git-rev-parse.txt b/Documentation/git-rev-parse.txt\nindex 2b126c0..7ec9221 100644\n--- a/Documentation/git-rev-parse.txt\n+++ b/Documentation/git-rev-parse.txt\n@@ -259,9 +259,10 @@ Each line of options has this format:\n \n ``::\n \t`` are of `*`, `=`, `?` or `!`.\n-\t* Use `=` if the option takes an argument.\n+\t* Use `=` if the option requires an argument.\n \n-\t* Use `?` to mean that the option is optional (though its use is discouraged).\n+\t* Use `?` if the option takes an optional argument (though its use is\n+\t discouraged).\n \n \t* Use `*` to mean that this option should not be listed in the usage\n \t generated for the `-h` argument. It's shown for `--help-all` as\n-- \n1.8.4\n"},{"id":"228930","messageId":"20131014143632.GD21200@google.com","threadId":"35137","inReplyTo":"1381760611-9573-1-git-send-email-boklm@mars-attacks.org","subject":"Re: [PATCH] rev-parse doc: clarify use of optional / required arguments","fromName":"Jonathan Nieder","fromEmail":"jrnieder@gmail.com","sentAt":"2013-10-14T14:36:32Z","receivedAt":"2013-10-14T14:36:32Z","isPatch":true,"sender":{"key":"jrnieder@gmail.com","avatar":"https://avatars.githubusercontent.com/u/281595?v=4"},"body":"Nicolas Vigier wrote:\n\n> \"the option is optional\" was confusing as it is not the option but its\n> argument which is optional.\n>\n> Signed-off-by: Nicolas Vigier \n\nThanks.\n\n[...]\n> --- a/Documentation/git-rev-parse.txt\n> +++ b/Documentation/git-rev-parse.txt\n> @@ -259,9 +259,10 @@ Each line of options has this format:\n[...]\n> -\t* Use `?` to mean that the option is optional (though its use is discouraged).\n> +\t* Use `?` if the option takes an optional argument (though its use is\n> +\t discouraged).\n\nThis still seems confusing: the argument's use is discouraged?\n\nWould something like the following make sense?\n\n\t* Use `?` if [...]. This is used for historical options\n\t that once took no argument and later gained an optional\n\t argument. Use of this feature for new options is\n\t discouraged.\n\nHope that helps,\nJonathan\n"},{"id":"228931","messageId":"20131014152529.GU4589@mars-attacks.org","threadId":"35137","inReplyTo":"20131014143632.GD21200@google.com","subject":"Re: [PATCH] rev-parse doc: clarify use of optional / required arguments","fromName":"Nicolas Vigier","fromEmail":"boklm@mars-attacks.org","sentAt":"2013-10-14T15:25:29Z","receivedAt":"2013-10-14T15:25:29Z","isPatch":true,"sender":{"key":"boklm@mars-attacks.org","avatar":"https://avatars.githubusercontent.com/u/405910?v=4"},"body":"On Mon, 14 Oct 2013, Jonathan Nieder wrote:\n\n> Nicolas Vigier wrote:\n> \n> > \"the option is optional\" was confusing as it is not the option but its\n> > argument which is optional.\n> >\n> > Signed-off-by: Nicolas Vigier \n> \n> Thanks.\n> \n> [...]\n> > --- a/Documentation/git-rev-parse.txt\n> > +++ b/Documentation/git-rev-parse.txt\n> > @@ -259,9 +259,10 @@ Each line of options has this format:\n> [...]\n> > -\t* Use `?` to mean that the option is optional (though its use is discouraged).\n> > +\t* Use `?` if the option takes an optional argument (though its use is\n> > +\t discouraged).\n> \n> This still seems confusing: the argument's use is discouraged?\n> \n> Would something like the following make sense?\n> \n> \t* Use `?` if [...]. This is used for historical options\n> \t that once took no argument and later gained an optional\n> \t argument. Use of this feature for new options is\n> \t discouraged.\n\nActually I don't know why it is discouraged, and I'm not sure that\nit should be. It was listed as discouraged since commit 21d47835 adding\nparseopt to git-rev-parse, but I have no idea why. I'm adding the author\nof this commit in Cc.\n\nThe reason that I looked at this documentation in the first place was\nthat I was looking at adding an option '-S[], --gpg-sign[=]'\nto git-rebase, similar to the option in git-commit, so that rebased\ncommits can be signed. In git-commit this option takes an optional argument,\nso I think it would make sense to make it optional in git-rebase too.\n"},{"id":"228980","messageId":"20131014235742.GF865149@vauxhall.crustytoothpaste.net","threadId":"35137","inReplyTo":"20131014152529.GU4589@mars-attacks.org","subject":"Re: [PATCH] rev-parse doc: clarify use of optional / required arguments","fromName":"brian m. carlson","fromEmail":"sandals@crustytoothpaste.net","sentAt":"2013-10-14T23:57:42Z","receivedAt":"2013-10-14T23:57:42Z","isPatch":true,"sender":{"key":"sandals@crustytoothpaste.net","avatar":"https://avatars.githubusercontent.com/u/497054?v=4"},"body":"On Mon, Oct 14, 2013 at 05:25:29PM +0200, Nicolas Vigier wrote:\n> The reason that I looked at this documentation in the first place was\n> that I was looking at adding an option '-S[], --gpg-sign[=]'\n> to git-rebase, similar to the option in git-commit, so that rebased\n> commits can be signed. In git-commit this option takes an optional argument,\n> so I think it would make sense to make it optional in git-rebase too.\n\nIt's funny you say that, because I literally started on that yesterday.\nI have cherry-pick and revert working, but I haven't gotten to anything\nelse yet. Feel free to work on it if you're interested, as I probably\nwon't get around to finishing it for some time.\n\n-- \nbrian m. carlson / brian with sandals: Houston, Texas, US\n+1 832 623 2791 | http://www.crustytoothpaste.net/~bmc | My opinion only\nOpenPGP: RSA v4 4096b: 88AC E9B2 9196 305B A994 7552 F1BA 225C 0223 B187\n"},{"id":"229002","messageId":"20131015104945.GW4589@mars-attacks.org","threadId":"35137","inReplyTo":"20131014235742.GF865149@vauxhall.crustytoothpaste.net","subject":"Re: [PATCH] rev-parse doc: clarify use of optional / required arguments","fromName":"Nicolas Vigier","fromEmail":"boklm@mars-attacks.org","sentAt":"2013-10-15T10:49:45Z","receivedAt":"2013-10-15T10:49:45Z","isPatch":true,"sender":{"key":"boklm@mars-attacks.org","avatar":"https://avatars.githubusercontent.com/u/405910?v=4"},"body":"On Mon, 14 Oct 2013, brian m. carlson wrote:\n\n> On Mon, Oct 14, 2013 at 05:25:29PM +0200, Nicolas Vigier wrote:\n> > The reason that I looked at this documentation in the first place was\n> > that I was looking at adding an option '-S[], --gpg-sign[=]'\n> > to git-rebase, similar to the option in git-commit, so that rebased\n> > commits can be signed. In git-commit this option takes an optional argument,\n> > so I think it would make sense to make it optional in git-rebase too.\n> \n> It's funny you say that, because I literally started on that yesterday.\n> I have cherry-pick and revert working, but I haven't gotten to anything\n> else yet. Feel free to work on it if you're interested, as I probably\n> won't get around to finishing it for some time.\n\nI have a patch for git-am working, but with a small problem : it has to\nassume that the optional argument to -S does not start with a dash.\nThis is because git-rev-parse --parseopt does not allow us to see the\ndifference between -S-q and -S -q, we don't know if -q is the next\noption or the argument to -S.\n\nMaybe that's the reason why the use of optional argument options with\ngit rev-parse --parseopt is discouraged ?\n\nI'm going to send a patch proposal so that rev-parse --parseopt gives an\nempty argument for an unset optional argument.\n\n"}]}