Re: [PATCH] rev-parse doc: clarify use of optional / required arguments

From: Nicolas Vigier <boklm@mars-attacks.org>
Date: Oct 14, 2013, 15:25 UTC
Message-ID: <20131014152529.GU4589@mars-attacks.org>
In-Reply-To: <20131014143632.GD21200@google.com>

On Mon, 14 Oct 2013, Jonathan Nieder wrote:

Show 26 quoted lines

> 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@mars-attacks.org>
> 
> 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.