@matheusbsbs / matheus-bagliano / commits / 1891261ed3
Fork 0

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 --------------