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

From: Junio C Hamano <[email-masked]>
Date: Thu, 11 May 2023 09:26:25 -0700

Sergey Organov <[email-masked]> writes:

> That said, there is another mystery in the diff interface as well: why
> do we have --patch-with-raw and --patch-with-stat, yet no
> --raw-with-stat, --numstat-with-shortstat, --patch-with-numstat, etc.?
> If, say, --patch turned off everything except usual diff output, then
> these combinatorical options would make sense, but currently they don't.

I can explain the mystery but the explanation may or may not justify
it, depending on how lenient you are to developers of old days, with
less experience than they have today ;-).

Back when we started, "--raw" was the only thing there, and then we
were to pass the raw-to-patch external filter, when you wanted a
patch output.  I then updated this arrangement to work in a single
process [*] without having to produce textual hexadecimal output
(raw) and piping it to another process, and that is how "--patch"
mode was created [*].

After I added "--patch", without having foresight of the risk of the
combinatorial explosion, "--patch-with-raw" was born.  "--stat" and
other niceties came much later, and made me finally realize the risk
of the combinatorial explosion.  "--patch-with-raw" stopped gaining
siblings as a consequence.

Yes, I was slow and inexperienced, but one has to do with the
capability one has at the time.

> Finally, there is another intrinsic problem in current Git CI: the
> "defaults to" part, as in "git show" that defaults to --patch for simple
> commits, --cc for merge commits, etc., except that it doesn't behave as
> if these options were explicitly provided at the beginning of the
> command-line.

Yes, as you said in your message after this part, this is pretty
much deliberate and is done for the sake of usability.  Essentially
the logic is to achieve two distinct goals:

 * we want to be able to combine the basic things like --patch,
   --raw, --stat to specify exact format (but some things may not
   mix well with others).

 * when the user does not give a specific preference, we want to
   give a reasonable default.

So, when the user wants "--stat", we do not want to combine it with
"--patch" that the user may have gotten by default if they did not
give "--stat".  If we implemented the default logic like the way (I
guess) you are suggesting, i.e.

 * there is a default set of options, "--patch".

 * the user can add or subtract options with "--[no-]foo" where the
   value of foo may be patch, stat, etc.

it would turn it to "--patch --stat" if the user gave "--stat" on
the command line.  The user needs to say "--no-patch --stat" if they
want to see only the diffstat (which by itself is not necessarily
bad; if it is more common to want --patch-with-stat than --stat, it
may even be better), but the bad part is that the user need to
remember what the built-in default is.

[Footnote]

* Not exactly a "single process"; until Linus imported xdiff
  machinery to make the textual patch generation in-process, we
  forked "diff -u" as a subprocess inside "git diff-*".  But the end
  user no longer had to construct the "git diff-files | raw-to-patch"
  pipeline themselves.

* Eventually it would become the in-process "diffcore transformation
  pipeline" to compute diff_queue, which is a moral equivalent of
  the input to "raw-to-patch filter", then transform the result of
  the previous step (e.g. rename detection) and then format the
  result of the previous step into various output, but none of that
  existed back then.