Understanding what git diff does

Question

I read from the man page for git diff that it should return "changes in the working tree not yet staged for the next commit". If I understood what the working tree is (it should be your local git repo working folder) when I add a new file to the my working directory I should see it returned by git diff and yet it return nothing. What I'm not getting?

Answer 1

Once you add a file (as in, I add it to index, which is what we normally mean when we say we add stuff in relation to git), it goes into the staged for next commit status and so it will go away from git diff by default. It will still be visible if you try git diff HEAD, though.

Answer 2

This has nothing to do with size. It has to do with how git "sees", and what you are asking for a difference between.

• First, there are three places: the HEAD (the most recent commit), the index (what you add to), and the worktree. So there are two "simple diff" commands:

  • git diff asks about differences between index and worktree.
  • git diff --cached asks about differences between HEAD and index.

• Second, what's not in the HEAD or the index does not exist as far as git is concerned; it is "untracked".

If a file is tracked (it's in the index or the HEAD), then changes in the worktree but not in the index are unstaged. But if a file is not tracked, then changes in the worktree are untracked; they have not yet reached the level of being unstaged, and they will not be in either kind of diff.

Okay. So when you first create a file, whether it has size or not, it is not yet in git's purview at all (it is untracked), so it is not part of any diff:

$ touch Z # this one has no size
$ echo testing > ZZ # this one has size
$ git diff # (crickets...)
$ git diff --cached # (crickets...)

Then when you add that file, now git knows about it (it is tracked). There is still no diff between the index and the workspace, because the index is identical to the workspace; you just copied those files from the latter to the former! But now a difference between HEAD and the index does exist:

$ git add .
$ git diff # (crickets...)
$ git diff --cached
diff --git a/Z b/Z
new file mode 100644
diff --git a/ZZ b/ZZ
new file mode 100644

Okay, so now those files are under git's supervision, because they are in the index. So now if we make a change in one of them (in the worktree), there is a difference (unstaged) between the index and worktree:

$ echo testing2 >> ZZ
$ git diff
diff --git a/ZZ b/ZZ
--- a/ZZ
+++ b/ZZ
@@ -1 +1,2 @@
 testing
+testing2

The same thing is true in reverse. To show what I mean, I'll add and commit everything; now there is no simple diff, as expected:

$ git add .
$ git commit -m'xxxx'
$ git diff # (crickets...)
$ git diff --cached # (crickets...)

Now I'll remove ZZ from the index, with rm, and from the HEAD, with commit:

$ git rm --cache ZZ
rm 'ZZ'
$ git commit -m'removed'

Now, once again, there is no difference between index and worktree, even though the file ZZ is still in the worktree:

$ git diff # (crickets...)
$ ls
Z   ZZ

That's because, since ZZ is no longer in HEAD or worktree, it is once again untracked; it is once again not part of git's purview.