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

From: Junio C Hamano <[email-masked]>
Date: Fri, 12 May 2023 10:03:51 -0700

Matthieu Moy <[email-masked]> writes:

> https://public-inbox.org/git/[email-masked]/
>
> 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.

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

Thanks.