Re: `git describe --dirty` doesn't consider untracked files to be dirty

[Junio C Hamano <gitster@pobox.com>]

Ash Holland <ash@sorrel.sh> writes:

> There seems to be a discrepancy between how `git describe --dirty` is
> documented and how it actually behaves. The documentation describes
> the --dirty flag like this:
>
>> If the working tree has local modification "-dirty" is appended to it.

Not limited to what "describe" does, whenever we mention "local
modification", we only mean modification to tracked contents,
because by definition we do not detect or track "modifications" to
anything that is not tracked.  Untracked paths may have been
modified multiple times, but since they are not even added, we do
not notice nor care.

That is to say that the documentation and the code are consistent
with each other.

Having said all that, a source that was forgotten to be added, yet
affects the built product by a build rule with wildcard e.g.
"compile all *.c files and link them into a single binary", would
happen in real life, so from that point of view, appending "-dirty"
only when there is a local modification may not be all that useful,
and tweaking the "--dirty" option to also pay attention to untracked
(but not ignored) might have merit.  

I do not think this is something we want to hide behind a
configuration knob, but I am undecided between (1) declare that this
is a bug and change the behaviour of "--dirty" and (2) declare that
we discovered another useful behaviour and add a new option next to
"--dirty".

Thanks.