builtin/describe.c: describe a blob
[git/git.git] / Documentation / git-describe.txt
CommitLineData
c06818e2
JH
1git-describe(1)
2===============
3
4NAME
5----
644eb60b 6git-describe - Give an object a human readable name based on an available ref
c06818e2
JH
7
8SYNOPSIS
9--------
c5b3e0f5 10[verse]
2bd07065 11'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
9f67d2e8 12'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
644eb60b 13'git describe' <blob>
c06818e2
JH
14
15DESCRIPTION
16-----------
17The command finds the most recent tag that is reachable from a
b7893cde
IH
18commit. If the tag points to the commit, then only the tag is
19shown. Otherwise, it suffixes the tag name with the number of
20additional commits on top of the tagged object and the
21abbreviated object name of the most recent commit.
c06818e2 22
7e425c4f
SP
23By default (without --all or --tags) `git describe` only shows
24annotated tags. For more information about creating annotated tags
25see the -a and -s options to linkgit:git-tag[1].
c06818e2 26
644eb60b
SB
27If the given object refers to a blob, it will be described
28as `<commit-ish>:<path>`, such that the blob can be found
29at `<path>` in the `<commit-ish>`, which itself describes the
30first commit in which this blob occurs in a reverse revision walk
31from HEAD.
32
c06818e2
JH
33OPTIONS
34-------
a8a5406a 35<commit-ish>...::
2bd07065 36 Commit-ish object names to describe. Defaults to HEAD if omitted.
c06818e2 37
9f67d2e8 38--dirty[=<mark>]::
b0176ce6
SB
39--broken[=<mark>]::
40 Describe the state of the working tree. When the working
41 tree matches HEAD, the output is the same as "git describe
42 HEAD". If the working tree has local modification "-dirty"
43 is appended to it. If a repository is corrupt and Git
44 cannot determine if there is local modification, Git will
45 error out, unless `--broken' is given, which appends
46 the suffix "-broken" instead.
9f67d2e8 47
c06818e2
JH
48--all::
49 Instead of using only the annotated tags, use any ref
831e61f8 50 found in `refs/` namespace. This option enables matching
29b9a66f 51 any known branch, remote-tracking branch, or lightweight tag.
c06818e2
JH
52
53--tags::
54 Instead of using only the annotated tags, use any tag
831e61f8 55 found in `refs/tags` namespace. This option enables matching
7e425c4f 56 a lightweight (non-annotated) tag.
c06818e2 57
23615708
SP
58--contains::
59 Instead of finding the tag that predates the commit, find
60 the tag that comes after the commit, and thus contains it.
61 Automatically implies --tags.
62
c06818e2 63--abbrev=<n>::
b938f62a 64 Instead of using the default 7 hexadecimal digits as the
492cf3f7
GA
65 abbreviated object name, use <n> digits, or as many digits
66 as needed to form a unique object name. An <n> of 0
67 will suppress long format, only showing the closest tag.
c06818e2 68
8713ab30
SP
69--candidates=<n>::
70 Instead of considering only the 10 most recent tags as
a8a5406a 71 candidates to describe the input commit-ish consider
8713ab30
SP
72 up to <n> candidates. Increasing <n> above 10 will take
73 slightly longer but may produce a more accurate result.
2c33f757
SP
74 An <n> of 0 will cause only exact matches to be output.
75
76--exact-match::
77 Only output exact matches (a tag directly references the
78 supplied commit). This is a synonym for --candidates=0.
8713ab30
SP
79
80--debug::
81 Verbosely display information about the searching strategy
82 being employed to standard error. The tag name will still
83 be printed to standard out.
c06818e2 84
518120e3
SB
85--long::
86 Always output the long format (the tag, the number of commits
87 and the abbreviated commit name) even when it matches a tag.
88 This is useful when you want to see parts of the commit object name
89 in "describe" output, even when the commit in question happens to be
90 a tagged version. Instead of just emitting the tag name, it will
492cf3f7
GA
91 describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2
92 that points at object deadbee....).
518120e3 93
30ffa603 94--match <pattern>::
52291497 95 Only consider tags matching the given `glob(7)` pattern,
6d68b2ab
MK
96 excluding the "refs/tags/" prefix. If used with `--all`, it also
97 considers local branches and remote-tracking references matching the
98 pattern, excluding respectively "refs/heads/" and "refs/remotes/"
99 prefix; references of other types are never considered. If given
100 multiple times, a list of patterns will be accumulated, and tags
101 matching any of the patterns will be considered. Use `--no-match` to
102 clear and reset the list of patterns.
30ffa603 103
77d21f29
JK
104--exclude <pattern>::
105 Do not consider tags matching the given `glob(7)` pattern, excluding
6d68b2ab
MK
106 the "refs/tags/" prefix. If used with `--all`, it also does not consider
107 local branches and remote-tracking references matching the pattern,
108 excluding respectively "refs/heads/" and "refs/remotes/" prefix;
109 references of other types are never considered. If given multiple times,
110 a list of patterns will be accumulated and tags matching any of the
111 patterns will be excluded. When combined with --match a tag will be
112 considered when it matches at least one --match pattern and does not
77d21f29
JK
113 match any of the --exclude patterns. Use `--no-exclude` to clear and
114 reset the list of patterns.
115
a3800f66
SB
116--always::
117 Show uniquely abbreviated commit object as fallback.
118
e00dd1e9
MC
119--first-parent::
120 Follow only the first parent commit upon seeing a merge commit.
121 This is useful when you wish to not match tags on branches merged
122 in the history of the target commit.
123
c06818e2
JH
124EXAMPLES
125--------
126
127With something like git.git current tree, I get:
128
b1889c36 129 [torvalds@g5 git]$ git describe parent
1891261e 130 v1.0.4-14-g2414721
c06818e2
JH
131
132i.e. the current head of my "parent" branch is based on v1.0.4,
323b9db8 133but since it has a few commits on top of that,
1891261e
JH
134describe has added the number of additional commits ("14") and
135an abbreviated object name for the commit itself ("2414721")
136at the end.
137
138The number of additional commits is the number
139of commits which would be displayed by "git log v1.0.4..parent".
140The hash suffix is "-g" + 7-char abbreviation for the tip commit
141of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`).
846b8f68
MH
142The "g" prefix stands for "git" and is used to allow describing the version of
143a software depending on the SCM the software is managed with. This is useful
144in an environment where people may use different SCMs.
c06818e2 145
0b444cdb 146Doing a 'git describe' on a tag-name will just show the tag name:
c06818e2 147
b1889c36 148 [torvalds@g5 git]$ git describe v1.0.4
c06818e2
JH
149 v1.0.4
150
151With --all, the command can use branch heads as references, so
152the output shows the reference path as well:
153
154 [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
1891261e 155 tags/v1.0.0-21-g975b
c06818e2 156
492cf3f7 157 [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
1891261e
JH
158 heads/lt/describe-7-g975b
159
160With --abbrev set to 0, the command can be used to find the
161closest tagname without any suffix:
162
163 [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
164 tags/v1.0.0
c06818e2 165
492cf3f7 166Note that the suffix you get if you type these commands today may be
0a565de4 167longer than what Linus saw above when he ran these commands, as your
2de9b711 168Git repository may have new commits whose object names begin with
492cf3f7
GA
169975b that did not exist back then, and "-g975b" suffix alone may not
170be sufficient to disambiguate these commits.
171
172
8713ab30
SP
173SEARCH STRATEGY
174---------------
175
a8a5406a 176For each commit-ish supplied, 'git describe' will first look for
8713ab30
SP
177a tag which tags exactly that commit. Annotated tags will always
178be preferred over lightweight tags, and tags with newer dates will
179always be preferred over tags with older dates. If an exact match
180is found, its name will be output and searching will stop.
181
0b444cdb 182If an exact match was not found, 'git describe' will walk back
8713ab30
SP
183through the commit history to locate an ancestor commit which
184has been tagged. The ancestor's tag will be output along with an
bcf9626a 185abbreviation of the input commit-ish's SHA-1. If `--first-parent` was
e00dd1e9
MC
186specified then the walk will only consider the first parent of each
187commit.
8713ab30
SP
188
189If multiple tags were found during the walk then the tag which
a8a5406a 190has the fewest commits different from the input commit-ish will be
8713ab30 191selected and output. Here fewest commits different is defined as
483bc4f0 192the number of commits which would be shown by `git log tag..input`
8713ab30
SP
193will be the smallest number of commits possible.
194
644eb60b
SB
195BUGS
196----
197
198Tree objects as well as tag objects not pointing at commits, cannot be described.
199When describing blobs, the lightweight tags pointing at blobs are ignored,
200but the blob is still described as <committ-ish>:<path> despite the lightweight
201tag being favorable.
202
c06818e2
JH
203GIT
204---
9e1f0a85 205Part of the linkgit:git[1] suite