Re: Can we clarify the purpose of `git diff -s`?

[Sergey Organov <sorganov@gmail.com>]

Junio C Hamano <gitster@pobox.com> writes:

> Matthieu Moy <Matthieu.Moy@univ-lyon1.fr> writes:
>
>> https://public-inbox.org/git/51E3DC47.70107@googlemail.com/
>>
>> Essentially, Stefan Beller was using 'git show --format="%ad"' and
>> expecting it to show only the author date, and for merge commits it
>> also showed the patch (--cc). I suggested -s and noticed that the
>> option wasn't easily discoverable, hence the patch series to better
>> document it and add --no-patch as a synonym.
>>
>> Probably I did not get all the subtleties of the different kinds of
>> outputs. I guess I considered the output of diff to be the one
>> specified by --format plus the patch (not considering --raw, --stat &
>> friends), hence "get only the output specified by --format" and
>> "disable the patch" were synonym to me.

So --no-patch, if it were made to disable only --patch from the
beginning, would still serve the purpose of solving of the original
problem, right? Please notice that --cc produces no output without
--patch. Thus, making --no-patch a synonym for -s was a mistake in the
first place that leaked through review process at that time, and

   git show --format="%ad" --no-patch

will still work the same way even if we fix --no-patch to disable
--patch only.

>
> Thanks for double checking.  It matches my recollection that we (you
> the author and other reviewers as well) added "--no-patch" back then
> to mean "no output from diff machinery, exactly the same as '-s' but
> use a name that is more discoverable".
>
>> Looking more closely, it's
>> rather clear to me they are not, and that
>>
>>   git show --raw --patch --no-patch
>>
>> should be equivalent to
>>
>>   git show --raw
>
> Yeah.  If this were 10 years ago and we were designing from scratch,
> the "no output from diff machinery, more discoverable alias for
> '-s'" would have been "--silent" or "--squelch" and we would made
> any "--no-<format>" to defeat only "--<format>".
>
> It is a different matter if we can safely change what "--no-patch"
> means _now_.  Given that "--no-patch" was introduced for the
> explicit purpose of giving "-s" a name that is easier to remember,
> and given that in the 10 years since we did so, we may have acquired
> at least a few more end users of Git than we used to have, hopefully
> your change have helped them discover and learn to use "--no-patch"
> to defeat any "--<format>" they gave earlier as initial options in
> their script, which will be broken and need to be updated to use a
> much less discoverable "-s".

Fortunately, whoever used --no-patch are very unlikely to actually rely
on it being a synonym for "-s", as it was always enough for them that
--no-patch disables --patch, that will still hold after the fix.

Taking this into account it should be pretty safe to fix that old
mistake, and then to address "-s" discoverability issue separately.

Finally, this safety concern is even less attractive provided recent
"-s" fix changed behavior more aggressively yet gets no such resistance.

Thanks,
-- Sergey Organov