From: Ævar Arnfjörð Bjarmason <avarab@gmail.com>
Date: Thu, 02 Aug 2018 14:21:19 GMT
Subject: Re: [PATCH] push: comment on a funny unbalanced option help
Message-ID: <87ftzwu9wg.fsf@evledraar.gmail.com>
In-Reply-To: <30a6105c-4cb7-b52f-0b0a-c4504b90a5b1@web.de>


On Thu, Aug 02 2018, René Scharfe wrote:

> Am 02.08.2018 um 00:31 schrieb Ævar Arnfjörð Bjarmason:
>> But looking at this again it looks like this whole thing should just be
>> replaced by:
>>
>>      diff --git a/builtin/push.c b/builtin/push.c
>>      index 9cd8e8cd56..b8fa15c101 100644
>>      --- a/builtin/push.c
>>      +++ b/builtin/push.c
>>      @@ -558,9 +558,10 @@ int cmd_push(int argc, const char **argv, const char *prefix)
>>                      OPT_BIT( 0,  "porcelain", &flags, N_("machine-readable output"), TRANSPORT_PUSH_PORCELAIN),
>>                      OPT_BIT('f', "force", &flags, N_("force updates"), TRANSPORT_PUSH_FORCE),
>>                      { OPTION_CALLBACK,
>>      -                 0, CAS_OPT_NAME, &cas, N_("refname>:<expect"),
>>      +                 0, CAS_OPT_NAME, &cas, N_("<refname>:<expect>"),
>>                        N_("require old value of ref to be at this value"),
>>      -                 PARSE_OPT_OPTARG, parseopt_push_cas_option },
>>      +                 PARSE_OPT_OPTARG | PARSE_OPT_LITERAL_ARGHELP,
>>      +                 parseopt_push_cas_option },
>>                      { OPTION_CALLBACK, 0, "recurse-submodules", &recurse_submodules, "check|on-demand|no",
>>                              N_("control recursive pushing of submodules"),
>>                              PARSE_OPT_OPTARG, option_parse_recurse_submodules },
>>
>> I.e. the reason this is confusing is because the code originally added
>> in 28f5d17611 ("remote.c: add command line option parser for
>> "--force-with-lease"", 2013-07-08) didn't use PARSE_OPT_LITERAL_ARGHELP,
>> which I also see is what read-tree etc. use already to not end up with
>> these double <>'s, see also 29f25d493c ("parse-options: add
>> PARSE_OPT_LITERAL_ARGHELP for complicated argh's", 2009-05-21).
>
> We could check if argh comes with its own angle brackets already and
> not add a second pair in that case, making PARSE_OPT_LITERAL_ARGHELP
> redundant in most cases, including the one above.  Any downsides?
> Too magical?

I'm more inclined to say that we should stop using
PARSE_OPT_LITERAL_ARGHELP in some of these cases, and change
"refname>:<expect" to "<refname>:<expect>" in push.c, so that the help
we emit is --force-with-lease[=<<refname>:<expect>>].

As noted in 29f25d493c this facility wasn't added with the intent
turning --refspec=<<refspec>> into --refspec=<refspec>, but to do stuff
like --option=<val1>[,<val2>] for options that take comma-delimited
options.

If we're magically removing <>'s we have no consistent convention to
tell apart --opt=<a|b|c> meaning "one of a, b or c", --refspec=<refspec>
meaning "the literal string 'refspec'" and --refspec=<<refspec>> meaning
add a <refspec> string, i.e. fill in your refspec here.