On Mon, 14 Oct 2013, Jonathan Nieder wrote: > Nicolas Vigier wrote: > > > "the option is optional" was confusing as it is not the option but its > > argument which is optional. > > > > Signed-off-by: Nicolas Vigier <boklm@xxxxxxxxxxxxxxxx> > > Thanks. > > [...] > > --- a/Documentation/git-rev-parse.txt > > +++ b/Documentation/git-rev-parse.txt > > @@ -259,9 +259,10 @@ Each line of options has this format: > [...] > > - * Use `?` to mean that the option is optional (though its use is discouraged). > > + * Use `?` if the option takes an optional argument (though its use is > > + discouraged). > > This still seems confusing: the argument's use is discouraged? > > Would something like the following make sense? > > * Use `?` if [...]. This is used for historical options > that once took no argument and later gained an optional > argument. Use of this feature for new options is > discouraged. Actually I don't know why it is discouraged, and I'm not sure that it should be. It was listed as discouraged since commit 21d47835 adding parseopt to git-rev-parse, but I have no idea why. I'm adding the author of this commit in Cc. The reason that I looked at this documentation in the first place was that I was looking at adding an option '-S[<keyid>], --gpg-sign[=<keyid>]' to git-rebase, similar to the option in git-commit, so that rebased commits can be signed. In git-commit this option takes an optional argument, so I think it would make sense to make it optional in git-rebase too. -- To unsubscribe from this list: send the line "unsubscribe git" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html