path: root/Documentation/git-describe.txt
diff options
authorJean Privat <>2009-10-21 13:35:22 (GMT)
committerJunio C Hamano <>2009-10-27 19:46:22 (GMT)
commit9f67d2e8279e1885ef2b4681c19cef8534259783 (patch)
treeec7b54330c38c9b7bff7574b9e8ddef66a09bca5 /Documentation/git-describe.txt
parent78d553b7d7b269bb22ebd8b1198657c37484a3a0 (diff)
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 <> Acked-by: Shawn O. Pearce <> Signed-off-by: Junio C Hamano <>
Diffstat (limited to 'Documentation/git-describe.txt')
1 files changed, 6 insertions, 0 deletions
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt
index b231dbb..5253d86 100644
--- a/Documentation/git-describe.txt
+++ b/Documentation/git-describe.txt
@@ -9,6 +9,7 @@ git-describe - Show the most recent tag that is reachable from a commit
'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>...
+'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
@@ -27,6 +28,11 @@ OPTIONS
Committish object names to describe.
+ Describe the working tree.
+ It means describe HEAD and appends <mark> (`-dirty` by
+ default) if the working tree is dirty.
Instead of using only the annotated tags, use any ref
found in `.git/refs/`. This option enables matching