Update describe documentation.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Jan 26, 2007 at 23:24 UTC
1891261ed3ed52022ae5322b4db338f9d5112909
1 file changed
+22
-9
Documentation/git-describe.txt
+22
-9
@@ -14,8 +14,8 @@ DESCRIPTION
14
-----------
15
The command finds the most recent tag that is reachable from a
16
commit, and if the commit itself is pointed at by the tag, shows
17
-the tag. Otherwise, it suffixes the tag name with abbreviated
18
-object name of the commit.
17
+the tag. Otherwise, it suffixes the tag name with the number of
18
+additional commits and the abbreviated object name of the commit.
19
20
21
OPTIONS
@@ -52,12 +52,18 @@ EXAMPLES
52
With something like git.git current tree, I get:
53
54
[torvalds@g5 git]$ git-describe parent
55
- v1.0.4-g2414721b
55
+ v1.0.4-14-g2414721
56
57
i.e. the current head of my "parent" branch is based on v1.0.4,
58
-but since it has a few commits on top of that, it has added the
59
-git hash of the thing to the end: "-g" + 8-char shorthand for
60
-the commit `2414721b194453f058079d897d13c4e377f92dc6`.
58
+but since it has a handful commits on top of that,
59
+describe has added the number of additional commits ("14") and
60
+an abbreviated object name for the commit itself ("2414721")
61
+at the end.
62
+
63
+The number of additional commits is the number
64
+of commits which would be displayed by "git log v1.0.4..parent".
65
+The hash suffix is "-g" + 7-char abbreviation for the tip commit
66
+of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`).
67
68
Doing a "git-describe" on a tag-name will just show the tag name:
69
@@ -68,10 +74,16 @@ With --all, the command can use branch heads as references, so
74
the output shows the reference path as well:
75
76
[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
71
- tags/v1.0.0-g975b
77
+ tags/v1.0.0-21-g975b
78
79
[torvalds@g5 git]$ git describe --all HEAD^
74
- heads/lt/describe-g975b
80
+ heads/lt/describe-7-g975b
81
+
82
+With --abbrev set to 0, the command can be used to find the
83
+closest tagname without any suffix:
84
+
85
+ [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
86
+ tags/v1.0.0
87
88
SEARCH STRATEGY
89
---------------
@@ -97,7 +109,8 @@ will be the smallest number of commits possible.
109
Author
110
------
111
Written by Linus Torvalds <torvalds@osdl.org>, but somewhat
100
-butchered by Junio C Hamano <junkio@cox.net>
112
+butchered by Junio C Hamano <junkio@cox.net>. Later significantly
113
+updated by Shawn Pearce <spearce@spearce.org>.
114
115
Documentation
116
--------------