15
15
The command finds the most recent tag that is reachable from a
16
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.
35
35
Instead of using the default 8 hexadecimal digits as the
36
36
abbreviated object name, use <n> digits.
39
Instead of considering only the 10 most recent tags as
40
candidates to describe the input committish consider
41
up to <n> candidates. Increasing <n> above 10 will take
42
slightly longer but may produce a more accurate result.
45
Verbosely display information about the searching strategy
46
being employed to standard error. The tag name will still
47
be printed to standard out.
42
52
With something like git.git current tree, I get:
44
54
[torvalds@g5 git]$ git-describe parent
47
57
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`.
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")
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`).
52
68
Doing a "git-describe" on a tag-name will just show the tag name:
58
74
the output shows the reference path as well:
60
76
[torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
63
79
[torvalds@g5 git]$ git describe --all HEAD^
64
heads/lt/describe-g975b
80
heads/lt/describe-7-g975b
82
With --abbrev set to 0, the command can be used to find the
83
closest tagname without any suffix:
85
[torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
91
For each committish supplied "git describe" will first look for
92
a tag which tags exactly that commit. Annotated tags will always
93
be preferred over lightweight tags, and tags with newer dates will
94
always be preferred over tags with older dates. If an exact match
95
is found, its name will be output and searching will stop.
97
If an exact match was not found "git describe" will walk back
98
through the commit history to locate an ancestor commit which
99
has been tagged. The ancestor's tag will be output along with an
100
abbreviation of the input committish's SHA1.
102
If multiple tags were found during the walk then the tag which
103
has the fewest commits different from the input committish will be
104
selected and output. Here fewest commits different is defined as
105
the number of commits which would be shown by "git log tag..input"
106
will be the smallest number of commits possible.
69
111
Written by Linus Torvalds <torvalds@osdl.org>, but somewhat
70
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>.
added
removed
Documentation/git-describe.txt
