diff options
| author |  Jean Privat <jean@pryen.org> | 2009-10-21 09:35:22 -0400 |
|---|---|---|
| committer |  Junio C Hamano <gitster@pobox.com> | 2009-10-27 12:46:22 -0700 |
| commit | 9f67d2e8279e1885ef2b4681c19cef8534259783 (patch) | |
| tree | ec7b54330c38c9b7bff7574b9e8ddef66a09bca5 /Documentation/git-describe.txt | |
| parent | GIT 1.6.5 (diff) | |
| download | tgif-9f67d2e8279e1885ef2b4681c19cef8534259783.tar.xz | |
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>
Diffstat (limited to 'Documentation/git-describe.txt')
| -rw-r--r-- | Documentation/git-describe.txt | 6 |
1 files changed, 6 insertions, 0 deletions
diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index b231dbb947..5253d86118 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 SYNOPSIS -------- 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>... +'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>] DESCRIPTION ----------- @@ -27,6 +28,11 @@ OPTIONS <committish>...:: Committish object names to describe. +--dirty[=<mark>]:: + Describe the working tree. + It means describe HEAD and appends <mark> (`-dirty` by + default) if the working tree is dirty. + --all:: Instead of using only the annotated tags, use any ref found in `.git/refs/`. This option enables matching |