archive mirror
 help / color / mirror / Atom feed
From: Felipe Contreras <>
Cc: Sergey Organov <>,
	Matthieu Moy <>
Subject: Can we clarify the purpose of `git diff -s`?
Date: Wed, 10 May 2023 21:14:40 -0600	[thread overview]
Message-ID: <645c5da0981c1_16961a29455@chronos.notmuch> (raw)

A recent discussion about a bug in the diff machinery [1] made me dig
the history of the `-s` option, and turned out to be quite an
archeological endeavor.

The first indication of such flag comes from e2e5e98a40 ([PATCH] Silent
flag for show-diff, 2005-04-13), only 54 commits after the initial

Not much later after, a `-z` option was added for some machine-readable
output in d94c6128e6 ([PATCH] show-diff -z option for machine readable
output., 2005-04-16).

Linus Torvalds wanted to make the machine-readable output the only one
and wrote 0a7668e99f (show-diff: match diff-tree and diff-cache output,
2005-04-26), but Junio Hamano disagreed and added a `-p` option for
a human-readable patch in 4a6bf9e18a ([PATCH] Reactivate show-diff patch
generation, 2005-04-27).

  You'll need "diff-tree-helper" to show the full diff, but Junio is
  dead set on adding a "-p" argument to all three to avoid it. That's

Right after that, Junio Hamano deprecated the `-s` flag, since
`git-show-diff` didn't show the patch by default, so `-s` became a
no-op. I presume at that point in time they didn't think of the
possibility of doing `-p -s` together.

The first introduction of DIFF_FORMAT_NO_OUTPUT was in a corner case of
6b14d7faf0 ([PATCH] Diffcore updates., 2005-05-22), but later on it was
used explicitly to replace a global variable of `git-diff-tree -s` in
d0309355c9 ([PATCH] Use DIFF_FORMAT_NO_OUTPUT to implement diff-tree -s
option., 2005-05-24).

When the equivalent of the modern `git diff` was added, the `-p` option
was included by default: 940c1bb018 (Add "git diff" script, 2005-06-13).
So later on when it was converted to C, DIFF_FORMAT_PATCH was the
default 65056021f2 (built-in diff., 2006-04-28).

But not for all commands, for example the default of `git diff-tree` is
DIFF_FORMAT_RAW, and it remains the case to this day.

So at this point it seems pretty clear that `-s` means `silent`, and
whatever the default format of a diff command is (`--patch` or `--raw`),
`-s` is meant to silence that format.

Later on in c6744349df (Merge with_raw, with_stat and summary variables
to output_format, 2006-06-24), the output format changed from an enum to
a bit field, so now it was possible to do for example

This is when things become complicated, because now what is `-s`
supposed to do? Is it supposed to silence only the default format? Or is
it supposed to silence all formats?

For example, these two commands are equivalent:

  git diff-tree @~ @
  git diff-tree --raw @~ @

That's because the default format of `git diff-tree` is DIFF_FORMAT_RAW.

But what happens if we do:

  git diff-tree -s --patch @~ @

Shall we silence only the RAW part, or the PATCH part as well?

And then, should these two be different?

  git diff-tree --patch -s @~ @
  git diff-tree -s --patch @~ @

This is something that wasn't discussed or explored at the time, so it
is unclear.

And then, finally, we have d09cd15d19 (diff: allow --no-patch as synonym
for -s, 2013-07-16), which very clearly says:

  This follows the usual convention of having a --no-foo option to
  negate --foo.

So, obviously the intention of `--no-patch` is to negate `--patch`, but
it is linked to `-s`, which was linked to DIFF_FORMAT_NO_OUTPUT, which
means `--no-patch` negates *all* output, not just the output of

So what should the output of this command be:

  git diff-tree --patch --no-patch --raw @~ @

I think it very clearly should output the same as:

  git diff-tree @~ @

And the ordering does not matter, as this should output the same:

  git diff-tree --raw --patch --no-patch @~ @

If we can combine two formats, for example:

  git diff --patch --raw @~

Then we should be able to negate a single format, for example:

  git diff --patch --raw --no-patch @~

Which in my mind should be different from:

  git diff --patch --raw --silent @~

So, in short: I don't think `-s` and `--no-patch` are the same thing at
all, and it was a mistake to link them together.

If anybody thinks the intention behind `-s` and `--no-patch` is
obviously clear, I think it would be helpful to explicitly say so for
the record.



Felipe Contreras

             reply	other threads:[~2023-05-11  3:14 UTC|newest]

Thread overview: 39+ messages / expand[flat|nested]  mbox.gz  Atom feed  top
2023-05-11  3:14 Felipe Contreras [this message]
2023-05-11 11:59 ` Can we clarify the purpose of `git diff -s`? Sergey Organov
2023-05-11 16:26   ` Junio C Hamano
2023-05-11 17:37   ` Junio C Hamano
2023-05-11 18:04     ` Sergey Organov
2023-05-11 18:27       ` Junio C Hamano
2023-05-11 18:36       ` Felipe Contreras
2023-05-11 18:17     ` Felipe Contreras
2023-05-11 17:41   ` Felipe Contreras
2023-05-11 18:31     ` Sergey Organov
2023-05-11 19:10       ` Felipe Contreras
2023-05-11 19:32         ` Sergey Organov
2023-05-11 19:54           ` Felipe Contreras
2023-05-11 20:24             ` Sergey Organov
2023-05-11 20:59               ` Felipe Contreras
2023-05-11 22:49                 ` Sergey Organov
2023-05-11 23:28                   ` Felipe Contreras
2023-05-12  8:40                     ` Sergey Organov
2023-05-12 19:19                       ` Felipe Contreras
     [not found]   ` <>
2023-05-12  8:15     ` Matthieu Moy
2023-05-12 17:03       ` Junio C Hamano
2023-05-12 18:21         ` Sergey Organov
2023-05-12 19:21           ` Junio C Hamano
2023-05-12 19:34             ` Junio C Hamano
2023-05-12 20:28             ` Felipe Contreras
2023-05-12 20:47               ` Junio C Hamano
2023-05-12 21:01                 ` Felipe Contreras
2023-05-12 21:47                   ` Junio C Hamano
2023-05-12 21:48                     ` Junio C Hamano
2023-05-12 23:21                     ` Felipe Contreras
2023-05-12 21:41                 ` Sergey Organov
2023-05-12 22:17                   ` Junio C Hamano
2023-05-12 22:47                     ` Sergey Organov
2023-05-12 23:07                   ` Felipe Contreras
2023-05-13 14:58                     ` Philip Oakley
2023-05-13 17:45                       ` Sergey Organov
2023-05-12 19:47           ` Felipe Contreras
2023-05-12 19:34         ` Felipe Contreras
2023-05-12 19:17       ` Felipe Contreras

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

  Avoid top-posting and favor interleaved quoting:

* Reply using the --to, --cc, and --in-reply-to
  switches of git-send-email(1):

  git send-email \
    --in-reply-to=645c5da0981c1_16961a29455@chronos.notmuch \ \ \ \ \

* If your mail client supports setting the In-Reply-To header
  via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).