git-describe: documentation.
Signed-off-by: Junio C Hamano <junkio@cox.net>
Junio C Hamano committed
Dec 27, 2005 at 16:10 UTC
c06818e20a88f58294de0a948a437c7c32c382fe
2 files changed
+82
Documentation/git-describe.txt
new
+79
@@ -0,0 +1,79 @@
1
+git-describe(1)
2
+===============
3
+
4
+NAME
5
+----
6
+git-describe - Show the most recent tag that is reachable from a commit.
7
+
8
+
9
+SYNOPSIS
10
+--------
11
+'git-describe' [--all] [--tags] [--abbrev=<n>] <committish>...
12
+
13
+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.
19
+
20
+
21
+OPTIONS
22
+-------
23
+<committish>::
24
+ The object name of the comittish.
25
+
26
+--all::
27
+ Instead of using only the annotated tags, use any ref
28
+ found in `.git/refs/`.
29
+
30
+--tags::
31
+ Instead of using only the annotated tags, use any tag
32
+ found in `.git/refs/tags`.
33
+
34
+--abbrev=<n>::
35
+ Instead of using the default 8 hexadecimal digits as the
36
+ abbreviated object name, use <n> digits.
37
+
38
+
39
+EXAMPLES
40
+--------
41
+
42
+With something like git.git current tree, I get:
43
+
44
+ [torvalds@g5 git]$ git-describe parent
45
+ v1.0.4-g2414721b
46
+
47
+i.e. the current head of my "parent" branch is based on v1.0.4,
48
+but since it has a few commits on top of that, it has added the
49
+git hash of the thing to the end: "-g" + 8-char shorthand for
50
+the commit `2414721b194453f058079d897d13c4e377f92dc6`.
51
+
52
+Doing a "git-describe" on a tag-name will just show the tag name:
53
+
54
+ [torvalds@g5 git]$ git-describe v1.0.4
55
+ v1.0.4
56
+
57
+With --all, the command can use branch heads as references, so
58
+the output shows the reference path as well:
59
+
60
+ [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
61
+ tags/v1.0.0-g975b
62
+
63
+ [torvalds@g5 git]$ git describe --all HEAD^
64
+ heads/lt/describe-g975b
65
+
66
+
67
+Author
68
+------
69
+Written by Linus Torvalds <torvalds@osdl.org>, but somewhat
70
+butchered by Junio C Hamano <junkio@cox.net>
71
+
72
+Documentation
73
+--------------
74
+Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
75
+
76
+GIT
77
+---
78
+Part of the gitlink:git[7] suite
79
+
Documentation/git.txt
+3
@@ -139,6 +139,9 @@ Interrogation commands
139
gitlink:git-cat-file[1]::
140
Provide content or type/size information for repository objects.
141
142
+gitlink:git-describe[1]::
143
+ Show the most recent tag that is reachable from a commit.
144
+
145
gitlink:git-diff-index[1]::
146
Compares content and mode of blobs between the index and repository.
147