They're actually both reasonable claims. I think the "best answer" is that both are wrong, although the former (the kernel.org version) is probably closer.
Consider:
$ mkdir /tmp/repo && cd /tmp/repo
$ git init
Initialized empty Git repository in /tmp/repo/.git/
$ echo contents > file
$ git add file
$ git commit -m initial
[master (root-commit) e1731a6] initial
1 file changed, 1 insertion(+)
create mode 100644 file
We now have a repository with one commit containing one file.
$ echo second line >> file; git add file; echo contents > file
At this point, the index has file
with two lines in it. But the work-tree version of file
has just the one line in it, and matches what's in the repository.
Is file
dirty? Well, git status --short
says that it is, twice (two M
s). Both git diff
and git diff --cached
show changes (so yes, it's "dirty"), but git diff HEAD
says there's no change, and if we git add
it again and try git status
:
$ git status --short
MM file
$ git diff HEAD
$ git add file
$ git status
# On branch master
nothing to commit, working directory clean
Let's put that odd change back and do one more thing. This time let's use the long form of git status
so that it gives us more information:
$ echo second line >> file; git add file; echo contents > file
$ git status
# On branch master
# Changes to be committed:
# (use "git reset HEAD <file>..." to unstage)
#
# modified: file
#
# Changes not staged for commit:
# (use "git add <file>..." to update what will be committed)
# (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified: file
#
It says we can use git reset
(which is the same as git reset --mixed
) with HEAD
and the file name to un-stage; surely that will make the working directory dirty? :-)
$ git reset HEAD file
$ git status
# On branch master
nothing to commit, working directory clean
No, in fact, it makes the working directory clean again! This follows from the (lack of) output of git diff HEAD
: "un-staging" the change that adds the second line makes the index refer to the HEAD
version, and the working-directory version is the same as the HEAD
version, so un-staging the "changes to be committed" causes there to be nothing to commit and no working-directory changes.
The "right" definition is, I think, that your tree is "clean" if there are no changes to commit and no changes between "tree staged for commit" (contents of index) and "work directory". However, it's reasonable to ask separately whether the index is clean (i.e., there is nothing staged for commit) and/or the work-tree is clean (unchanged) with respect to fill-in-the-blank, where the blank can be filled in with "the staging area" or "the HEAD
commit".
What git status
tells you is both the answer to "what, if anything, is staged for commit" and "what, if anything, is different between the work-tree and the index". You have to use git diff HEAD
(you may want to add --name-only
or similar) to see what, if anything, is different between the work-tree and the HEAD
commit unless (as is often the case) the index matches the HEAD
commit.