Why is `git describe -dirty` adding a `-dirty` suffix when describing a clean checkout?

Question

I have just discovered the --dirty option to git describe and it looks like it should do something very useful, i.e. append a suffix to the output of git describe when the working tree is dirty, however that doesn't seem to be the case on some of my repositories:

$ git status
# On branch 8.30
nothing to commit (working directory clean)
$ git describe --dirty
8.30rel-8-g9c1cbdb-dirty

I thought this might be because the working directory is dirty relative to the tag, but that doesn't seem to be the case either:

$ git status
# On branch 1.4
nothing to commit (working directory clean)
$ git describe --tags --dirty --long
1.4rel-0-gfedfe66-dirty

I used to make extensive use of hg id when I used to use Mercurial and liked the fact that it's default behaviour was to add a + suffix to any commit hash it reported for a dirty repository, so have been looking out for a git equivalent since, but git describe --dirty doesn't appear to do what I would expect given the documentation:

   --dirty[=<mark>]
       Describe the working tree. It means describe HEAD and appends
       <mark> (-dirty by default) if the working tree is dirty.

Am I misunderstanding what --dirty should do, or am I not using it correctly?

In case it makes any difference, all of the git repositories are deployed via buckminster so there are no submodules involved and the filesystem is an nfs share.

---

Update: I have discovered a work around, but I have absolutely no idea how this could possibly be making a difference.

If I run git diff --quiet HEAD on the repo then all of a sudden the git describe works as I expect:

$ git status
# On branch 8.30
nothing to commit (working directory clean)
$ git describe --dirty
8.30rel-8-g9c1cbdb-dirty
$ git diff --quiet HEAD
$ git describe --dirty
8.30rel-8-g9c1cbdb

I also spotted that when git describe was reporting the repository as dirty then gitk also showed "Local uncommitted changes, not checked in to index" and then listed each file in the working directory, but with no diffs against them, just the ---- filename ---- lines.

---

Further update: As this continued to be a problem, I eventually wrote a git-describe-dirty script, which starts by running git describe --dirty but if it finds the repository to be dirty, runs git update-index -q --refresh before trying again and taking the second result.

When iterating through hundreds of repositories, using git describe-dirty and only running the index update for a repository which initially indicates it is dirty saves a great deal of time compared to running git update-index -q --refresh ; git describe --dirty every time.

Answer 1

If you are running git 1.7.6 or earlier, you need to run git update-index --refresh before using git describe --dirty, because the index may be stale. Your workaround of using git diff --quiet HEAD works because "git diff" is a porcelain command, and probably updates the index itself.

The git commit that fixes this for git 1.7.7 describes the problem:

When running git describe --dirty the index should be refreshed. Previously the cached index would cause describe to think that the index was dirty when, in reality, it was just stale.

Note that the exact sequence of steps you describe shouldn't have this problem, because git status updates the index. But I still think you are seeing this same issue because the workaround you describe matches. Here is how I demonstrate the issue:

% git describe --tags --dirty
v1.0.0
% touch pom.xml
% git describe --tags --dirty
v1.0.0-dirty
% git status
# On branch dev
nothing to commit (working directory clean)
% git describe --tags --dirty
v1.0.0

Here running "git status" updates the index as a side effect and fixes "git describe" output, just as with your workaround. The proper plumbing fix for git 1.7.6 and earlier would be:

% touch pom.xml
% git describe --tags --dirty
v1.0.0-dirty
% git update-index --refresh
% git describe --tags --dirty
v1.0.0

Answer 2

Git 2.13 (Q2 2017) improves a bit on that --dirty flag with a --broken one, since "git describe --dirty" dies when it cannot be determined if the state in the working tree matches that of HEAD (e.g. broken repository or broken submodule).

See commit b0176ce (21 Mar 2017) by Stefan Beller (stefanbeller).
^{(Merged by Junio C Hamano -- gitster -- in commit 844768a, 27 Mar 2017)}

builtin/describe: introduce --broken flag

git-describe tells you the version number you're at, or errors out, e.g. when you run it outside of a repository, which may happen when downloading a tar ball instead of using git to obtain the source code.

To keep this property of only erroring out, when not in a repository, severe (submodule) errors must be downgraded to reporting them gently instead of having git-describe error out completely.

To achieve that a flag '--broken' is introduced, which is in the same vein as '--dirty' but uses an actual child process to check for dirtiness. When that child dies unexpectedly, we'll append '-broken' instead of '-dirty'.