Subject: Re: [PATCH] push: comment on a funny unbalanced option help

From: Ævar Arnfjörð Bjarmason <[email-masked]>
Date: Thu, 02 Aug 2018 00:31:33 +0200

On Wed, Aug 01 2018, Junio C Hamano wrote:

> Ævar Arnfjörð Bjarmason <[email-masked]> writes:
>
>>> +		  /* N_() will get "<>" around, resulting in "<refname>:<expect>" */
>>
>> ...but this comment isn't accurate at all, N_() doesn't wrap the string
>> with <>'s, as can be seen by applying this patch:
>
> I know.  It is a short-hand for "what's inside N_() we see here".
> Try to come up with an equivalent that fits on a 80-char line.

I was going to say:

/* parse_options() will munge this to "<refname>:<expect>" */

or:

/* note: parse_options() will add surrounding <>'s for us */

or:

/* missing <>'s are not a bug, parse_options() adds them */

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).