@matheusbsbs / matheus-bagliano / commits / c06818e20a
Fork 0

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