From: Junio C Hamano <gitster@pobox.com>
Date: Thu, 24 Mar 2022 17:13:36 GMT
Subject: Re: [PATCH v2 0/3] reset: make --no-refresh the only way to skip index refresh
Message-ID: <xmqqsfr7jmtb.fsf@gitster.g>
In-Reply-To: <6d424915-5c63-bebd-f3b5-f153a541d077@gmail.com>

Phillip Wood <phillip.wood123@gmail.com> writes:

> I should have been clearer in my comments that I think changing the
> option name no '--no-refresh' whilst retaining '--refresh' is 
> worthwhile. '--no-refresh' is the form that users will want most of
> the time and changing the option name means that the useful version
> will be shown by "reset -h".

I am OK with it shown as "--[no-]refresh" or even "--refresh" alone,
as long as the description describes the "refresh" behaviour and
makes it clear that it is the default, with the expectation that the
users know from other boolean options that "--option" listed in "-h"
would naturally take "--no-option".

But as posted, 

    $ rungit seen reset -h 2>&1 | grep refresh
        --refresh             skip refreshing the index after reset

the explanation given is for "--no-refresh" (which is wrong), so
we'd need some fix in the area.  We could rephrase it to read

        --refresh             refresh the index after reset (default)

but as you suggested, I think mimicking how existing commands with
"--no-<option>" are shown, e.g. builtlin/update-ref.c does
"--no-deref",

    $ git update-ref -h 2>&1 | grep deref
        --no-deref            update <refname> not the one it points to
    $ git grep 'OPT_BOOL.*"no-deref"'
    builtin/update-ref.c:		OPT_BOOL( 0 , "no-deref", &no_deref,

would be a good approach.

> The range-diff for the other changes looks good

Thanks.

#leftoverbit: we may want to discuss if it is a good idea to teach
OPT_BOOL() to list "--[no-]<option>" in "git cmd -h", instead of
just "--<option>".