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

From: Felipe Contreras <felipe.contreras@gmail.com>
Date: May 12, 2023, 19:34 UTC
Message-ID: <645e94d38510f_21989f294c6@chronos.notmuch>
In-Reply-To: <xmqqo7mpqy6g.fsf@gitster.g>

Junio C Hamano wrote:

Show 37 quoted lines

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

We can. As we have been able to do backwards-incompatible changes in the past, will keep doing in the future.

You yourself proposed a backwards-incompatible change here [1].

Show 7 quoted lines

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

That is not true.

`--no-patch` is not used to defeat any `--<format>`, it's used to disable output, for example this:

  git show --no-patch

There is zero point in writing:

  git show --patch --no-patch

Because `--patch` is already the default.

But all of these would keep working fine if we change the semantics of `--no-patch`.

It's not true that they will be broken.

It's only when the default is a format other than patch, or a format other than patch is explicitely specified, for example:

  git diff-files --no-patch
  git show --raw --no-patch

Potentially the number of users who actually do this is *zero*.

A few users for some reason may have come to rely on the above behavior, but a few users might have come to rely on the following behavior as well:

  git show -s --raw

Which your patch [1] breaks.

[1] https://lore.kernel.org/git/20230505165952.335256-1-gitster@pobox.com/

-- 
Felipe Contreras