From: Nicolas Vigier <boklm@mars-attacks•org>
To: Jonathan Nieder <jrnieder@gmail•com>
Cc: git@vger•kernel.org, Pierre Habouzit <madcoder@debian•org>
Subject: Re: [PATCH] rev-parse doc: clarify use of optional / required arguments
Date: Mon, 14 Oct 2013 17:25:29 +0200 [thread overview]
Message-ID: <20131014152529.GU4589@mars-attacks.org> (raw)
In-Reply-To: <20131014143632.GD21200@google.com>
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@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.
next prev parent reply other threads:[~2013-10-14 15:25 UTC|newest]
Thread overview: 5+ messages / expand[flat|nested] mbox.gz Atom feed top
2013-10-14 14:23 [PATCH] rev-parse doc: clarify use of optional / required arguments Nicolas Vigier
2013-10-14 14:36 ` Jonathan Nieder
2013-10-14 15:25 ` Nicolas Vigier [this message]
2013-10-14 23:57 ` brian m. carlson
2013-10-15 10:49 ` Nicolas Vigier
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20131014152529.GU4589@mars-attacks.org \
--to=boklm@mars-attacks$(echo .)org \
--cc=git@vger$(echo .)kernel.org \
--cc=jrnieder@gmail$(echo .)com \
--cc=madcoder@debian$(echo .)org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox