From 9f67d2e8279e1885ef2b4681c19cef8534259783 Mon Sep 17 00:00:00 2001 From: Jean Privat Date: Wed, 21 Oct 2009 09:35:22 -0400 Subject: 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 --- Documentation/git-describe.txt | 6 ++++++ 1 file changed, 6 insertions(+) (limited to 'Documentation/git-describe.txt') 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=] ... +'git describe' [--all] [--tags] [--contains] [--abbrev=] --dirty[=] DESCRIPTION ----------- @@ -27,6 +28,11 @@ OPTIONS ...:: Committish object names to describe. +--dirty[=]:: + Describe the working tree. + It means describe HEAD and appends (`-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 -- cgit v1.2.3 From 492cf3f72f9d8a0308cc42a9ffc00ef782c88a20 Mon Sep 17 00:00:00 2001 From: Gisle Aas Date: Thu, 29 Oct 2009 22:29:35 +0100 Subject: More precise description of 'git describe --abbrev' Also adds a note about why the output in the examples might give different output today. Signed-off-by: Gisle Aas Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 17 +++++++++++++---- 1 file changed, 13 insertions(+), 4 deletions(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index b231dbb947..e9dbca7d87 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -44,7 +44,9 @@ OPTIONS --abbrev=:: Instead of using the default 7 hexadecimal digits as the - abbreviated object name, use digits. + abbreviated object name, use digits, or as many digits + as needed to form a unique object name. An of 0 + will suppress long format, only showing the closest tag. --candidates=:: Instead of considering only the 10 most recent tags as @@ -68,8 +70,8 @@ OPTIONS This is useful when you want to see parts of the commit object name in "describe" output, even when the commit in question happens to be a tagged version. Instead of just emitting the tag name, it will - describe such a commit as v1.2-0-deadbeef (0th commit since tag v1.2 - that points at object deadbeef....). + describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 + that points at object deadbee....). --match :: Only consider tags matching the given pattern (can be used to avoid @@ -108,7 +110,7 @@ the output shows the reference path as well: [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2 tags/v1.0.0-21-g975b - [torvalds@g5 git]$ git describe --all HEAD^ + [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^ heads/lt/describe-7-g975b With --abbrev set to 0, the command can be used to find the @@ -117,6 +119,13 @@ closest tagname without any suffix: [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2 tags/v1.0.0 +Note that the suffix you get if you type these commands today may be +longer than what Linus saw above when he ran this command, as your +git repository may have new commits whose object names begin with +975b that did not exist back then, and "-g975b" suffix alone may not +be sufficient to disambiguate these commits. + + SEARCH STRATEGY --------------- -- cgit v1.2.3 From 0a565de4a50032339d3786d366e70912a4dcf572 Mon Sep 17 00:00:00 2001 From: Gisle Aas Date: Wed, 4 Nov 2009 22:57:46 +0100 Subject: Fix documentation grammar typo Introduced in 492cf3f (More precise description of 'git describe --abbrev', 2009-10-29) Signed-off-by: Gisle Aas Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index e9dbca7d87..2f97916781 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -120,7 +120,7 @@ closest tagname without any suffix: tags/v1.0.0 Note that the suffix you get if you type these commands today may be -longer than what Linus saw above when he ran this command, as your +longer than what Linus saw above when he ran these commands, as your git repository may have new commits whose object names begin with 975b that did not exist back then, and "-g975b" suffix alone may not be sufficient to disambiguate these commits. -- cgit v1.2.3 From c5b3e0f54950f983836970050406347ddf82b152 Mon Sep 17 00:00:00 2001 From: Junio C Hamano Date: Tue, 10 Nov 2009 14:06:41 -0800 Subject: git-describe.txt: formatting fix A multi-line SYNOPSIS description must be marked as [verse] Signed-off-by: Junio C Hamano --- Documentation/git-describe.txt | 1 + 1 file changed, 1 insertion(+) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index d7329eb4c0..78b9808aa3 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -8,6 +8,7 @@ git-describe - Show the most recent tag that is reachable from a commit SYNOPSIS -------- +[verse] 'git describe' [--all] [--tags] [--contains] [--abbrev=] ... 'git describe' [--all] [--tags] [--contains] [--abbrev=] --dirty[=] -- cgit v1.2.3 From 0b444cdb19bcfcc7f59b7b00783cbfbbc5ddcf63 Mon Sep 17 00:00:00 2001 From: Thomas Rast Date: Sun, 10 Jan 2010 00:33:00 +0100 Subject: Documentation: spell 'git cmd' without dash throughout The documentation was quite inconsistent when spelling 'git cmd' if it only refers to the program, not to some specific invocation syntax: both 'git-cmd' and 'git cmd' spellings exist. The current trend goes towards dashless forms, and there is precedent in 647ac70 (git-svn.txt: stop using dash-form of commands., 2009-07-07) to actively eliminate the dashed variants. Replace 'git-cmd' with 'git cmd' throughout, except where git-shell, git-cvsserver, git-upload-pack, git-receive-pack, and git-upload-archive are concerned, because those really live in the $PATH. --- Documentation/git-describe.txt | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'Documentation/git-describe.txt') diff --git a/Documentation/git-describe.txt b/Documentation/git-describe.txt index 78b9808aa3..6fc5323ee6 100644 --- a/Documentation/git-describe.txt +++ b/Documentation/git-describe.txt @@ -106,7 +106,7 @@ of commits which would be displayed by "git log v1.0.4..parent". The hash suffix is "-g" + 7-char abbreviation for the tip commit of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). -Doing a 'git-describe' on a tag-name will just show the tag name: +Doing a 'git describe' on a tag-name will just show the tag name: [torvalds@g5 git]$ git describe v1.0.4 v1.0.4 @@ -136,13 +136,13 @@ be sufficient to disambiguate these commits. SEARCH STRATEGY --------------- -For each committish supplied, 'git-describe' will first look for +For each committish supplied, 'git describe' will first look for a tag which tags exactly that commit. Annotated tags will always be preferred over lightweight tags, and tags with newer dates will always be preferred over tags with older dates. If an exact match is found, its name will be output and searching will stop. -If an exact match was not found, 'git-describe' will walk back +If an exact match was not found, 'git describe' will walk back through the commit history to locate an ancestor commit which has been tagged. The ancestor's tag will be output along with an abbreviation of the input committish's SHA1. -- cgit v1.2.3