Re: [RFC PATCH] Using no- for options instead of duplication

[Junio C Hamano <gitster@pobox.com>]

Fredi Fowler <inredikawb@gmail.com> writes:

Here is a space for you to justify the change and sign off your
patch (see Documentation/SubmittingPatches).

> ---

> Subject: Re: [RFC PATCH] Using no- for options instead of duplication

Try to see if you can format the title in "<area>: <explanation>"
form first, please.  I'll come back to it later.


>  Documentation/merge-options.txt | 21 +++++++--------------
>  1 file changed, 7 insertions(+), 14 deletions(-)

A quick counting (which may count false positives) tells me that

    $ git grep -e '^--no-' Documentation | wc -l
    124 
    $ git grep -e '^--\[no-' Documentation | wc -l
    44

you are standardizing to the minority way.

	A tangent that somebody might want to tackle.  It would be
	nice if we had a tool that takes a grep expression (like
	'^--no' and '^\[no-' above) and shows histograms of the ages
	of lines that match.  It might tell us that all 44 combined
	ones are more recent (some of them may even have been
	updated from the separate form) than the 124 separate ones,
	in which case we can say "we started the process of
	migrating to list options singly, like '--[no-]option', in
	commit X; let's continue doing so" in the log message.  Or
	it may turn out that we have been going in the other
	direction and most of these 44 are stale ones yet to be
	split.  Without such a tool, the above numbers are the best
	measure to go by, which is not quite ideal.

As there are tons of split ones, not just in merge-options.txt, I
suspect that the <area> of the change can just be "doc", so a good
title may be

	Subject: [PATCH] doc: list negative options as --[no-]option

or something like that.

If going in the direction of this patch were a good idea, that is.

I am actually not sure if it is a good idea, especially given that
the only change is the enumeration headers and without adjustment to
the text, though.

> diff --git a/Documentation/merge-options.txt b/Documentation/merge-options.txt
> index 63a3fc09548ab..fc1122ded51a0 100644
> --- a/Documentation/merge-options.txt
> +++ b/Documentation/merge-options.txt
> @@ -1,5 +1,4 @@
> ---commit::
> ---no-commit::
> +--[no-]commit::
>  	Perform the merge and commit the result. This option can
>  	be used to override --no-commit.
>  +
>  ...
>  With --no-commit perform the merge but pretend the merge
>  failed and do not autocommit, to give the user a chance to
>  inspect and further tweak the merge result before committing.

For example, the original for this one gives the behaviour for --commit
and --no-commit separately, and it visually makes it easier to see two
distinct header items.

Description of some other options read OK either way, which would
justify not touching the description when combining two headings
into one.  But that still does not justify the combining in the
first place.

FWIW, "git help -m merge" begins its OPTIONS section like this:

OPTIONS
       --commit, --no-commit
           Perform the merge and commit the result. This option can be used to
           override --no-commit.

           With --no-commit perform the merge but pretend the merge failed and
           do not autocommit, to give the user a chance to inspect and further
           tweak the merge result before committing.

which is different from heading with a single "--[no-]commit", but I
do not quite see why a single squished form is preferrable.  It does
not save lines, and it forces readers to split and reassemble two
options in their head while reading.