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

[Felipe Contreras <felipe.contreras@gmail.com>]

Sergey Organov wrote:
> 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.

Indeed.

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

That's right.

And let's be realistic for a moment: nobody actually does `git diff-files
--raw`, as that's essentially the same as `cat /dev/null`: a no-op.

The reason `--no-patch` was added was to silenced the diff output of commands
that show a diff *in addition* to something else by default, like `git show`,
and `git show --no-patch` will keep working fine.

Why would anybody do `git show --raw --no-patch` when they can do
`git show --no-patch`?

Yet once again we are doing premature defense for a set of users that probably
don't even exist.

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

Exactly.

---

And this is yet another example of why git's UI is stuck and cannot (and
probably will never) be fixed.

Cheers.

-- 
Felipe Contreras