JHZ JHZ - 1 month ago 9
Git Question

What does the "diff --git" output in "git diff" refer to?

When I run

git diff
, the output begins with:

diff --git a/foo/bar b/foo/bar


If I try to run plain old
diff --git
, I'm told that the
--git
option doesn't exist (obviously, I guess, it would seem silly for a low-level tool to know about a specific DVCS). There's no mention of it in the
man
page as well. Where does this come from?

Answer

It's an "imaginary diff option", used to indicate to the reader that it's not just the output of running the diff command. For example, in git's own git repo:

$ git diff HEAD~1..HEAD | head
diff --git Documentation/git.txt Documentation/git.txt
index bd659c4..7913fc2 100644
--- Documentation/git.txt
+++ Documentation/git.txt
@@ -43,6 +43,11 @@ unreleased) version of Git, that is available from the 'master'
 branch of the `git.git` repository.
 Documentation for older releases are available here:

+* link:v2.10.0/git.html[documentation for release 2.10]
+
$ 

The diff command itself, if you invoked it with the same file name twice, would show no differences. git presumably creates temporary files corresponding to two different versions of Documentation/git.txt and feeds them to diff -- but the names of those temporary files would not be useful. I think git diff massages the output of diff to make it more meaningful to the reader.

Diving into the git source code, diff.c has the string "diff --git" hardwired as a string literal:

strbuf_addf(&header, "%s%sdiff --git %s %s%s\n", line_prefix, meta, a_one, b_two, reset);

And looking into the history of diff.c for the earliest version that contains that string:

$ git log -n 1 b58f23b3
commit b58f23b38a9a9f28d751311353819d3cdf6a86da
Author: Junio C Hamano <junkio@cox.net>
Date:   2005-05-18 09:10:47 -0700

    [PATCH] Fix diff output take #4.

    This implements the output format suggested by Linus in
    <Pine.LNX.4.58.0505161556260.18337@ppc970.osdl.org>, except the
    imaginary diff option is spelled "diff --git" with double dashes as
    suggested by Matthias Urlichs.

    Signed-off-by: Junio C Hamano <junkio@cox.net>
    Signed-off-by: Linus Torvalds <torvalds@osdl.org>
$ 

Presumably <Pine.LNX...> is the message-id of some email message in a mailing list somewhere. In any case, this commit message makes it clear that diff --git is an "imaginary diff option".

This email message, cited by nos in a comment, appears to be part of the discussion that led to this.

Comments