Teach "git describe" --dirty option

With the --dirty option, git describe works on HEAD but append s"-dirty"
iff the contents of the work tree differs from HEAD.  E.g.

  $ git describe --dirty
  v1.6.5-15-gc274db7
  $ echo >> Makefile
  $ git describe --dirty
  v1.6.5-15-gc274db7-dirty

The --dirty option can also be used to specify what is appended, instead
of the default string "-dirty".

  $ git describe --dirty=.mod
  v1.6.5-15-gc274db7.mod

Many build scripts use `git describe` to produce a version number based on
the description of HEAD (on which the work tree is based) + saying that if
the build contains uncommitted changes.  This patch helps the writing of
such scripts since `git describe --dirty` does directly the intended thing.

Three possiblities were considered while discussing this new feature:

1. Describe the work tree by default and describe HEAD only if "HEAD" is
   explicitly specified

     Pro: does the right thing by default (both for users and for scripts)
     Pro: other git commands that works on the work tree by default
     Con: breaks existing scripts used by the Linux kernel and other projects

2. Use --worktree instead of --dirty

     Pro: does what it says: "git describe --worktree" describes the work tree
     Con: other commands do not require a --worktree option when working
          on the work tree (it often is the default mode for them)
     Con: unusable with an optional value: "git describe --worktree=.mod"
	  is quite unintuitive.

3. Use --dirty as in this patch

     Pro: makes sense to specify an optional value (what the dirty mark is)
     Pro: does not have any of the big cons of previous alternatives
	  * does not break scripts
	  * is not inconsistent with other git commands

This patch takes the third approach.

Signed-off-by: Jean Privat <jean@pryen.org>
Acked-by: Shawn O. Pearce <spearce@spearce.org>
Signed-off-by: Junio C Hamano <gitster@pobox.com>

1 files changed, 14 insertions, 0 deletions

diff --git a/t/t6120-describe.sh b/t/t6120-describe.sh
index 8c7e081c53..100c4d99fb 100755
--- a/t/t6120-describe.sh
+++ b/t/t6120-describe.sh
@@ -123,6 +123,20 @@ test_expect_success 'rename tag Q back to A' '
 test_expect_success 'pack tag refs' 'git pack-refs'
 check_describe A-* HEAD
 
+check_describe "A-*[0-9a-f]" --dirty
+
+test_expect_success 'set-up dirty work tree' '
+	echo >>file
+'
+
+check_describe "A-*[0-9a-f]-dirty" --dirty
+
+check_describe "A-*[0-9a-f].mod" --dirty=.mod
+
+test_expect_success 'describe --dirty HEAD' '
+	test_must_fail git describe --dirty HEAD
+'
+
 test_expect_success 'set-up matching pattern tests' '
 	git tag -a -m test-annotated test-annotated &&
 	echo >>file &&