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 <

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

Beware that there was another bug fix regarding git describe --dirty, about a year ago: https://github.com/git/git/commit/a1e19004e11dcbc0ceebd92c425ceb1770e52d0b

"git --work-tree=$there --git-dir=$here describe --dirty" did not work correctly as it did not pay attention to the location of the worktree specified by the user

In case of this bug, the workarounds shown here didn't work, so we had to upgrade our installation. There seems to be no fix readily available for Debian buster as of today (2020-02-20), yet the Debian bullseye main git packages are compatible with buster right now.

Answer 3

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'.