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

From: Junio C Hamano <gitster@pobox.com>
Date: May 11, 2023, 16:26 UTC
Message-ID: <xmqqpm76ygum.fsf@gitster.g>
In-Reply-To: <871qjn2i63.fsf@osv.gnss.ru>

Sergey Organov <sorganov@gmail.com> writes:

Show 5 quoted lines

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

Show 5 quoted lines

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