blob: 08ff715709ccd1190cf9769c84a49322300a308e [file] [log] [blame]
Junio C Hamanoc06818e2005-12-27 16:10:56 -08001git-describe(1)
2===============
3
4NAME
5----
Stefan Beller644eb602017-11-15 18:00:39 -08006git-describe - Give an object a human readable name based on an available ref
Junio C Hamanoc06818e2005-12-27 16:10:56 -08007
8SYNOPSIS
9--------
Junio C Hamanoc5b3e0f2009-11-10 14:06:41 -080010[verse]
SZEDER Gábor2bd07062015-08-24 18:15:18 +020011'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
Jean Privat9f67d2e2009-10-21 09:35:22 -040012'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
Stefan Beller644eb602017-11-15 18:00:39 -080013'git describe' <blob>
Junio C Hamanoc06818e2005-12-27 16:10:56 -080014
15DESCRIPTION
16-----------
17The command finds the most recent tag that is reachable from a
Ian Hiltb7893cd2008-05-14 14:30:55 -040018commit. 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
Frederick Eaton55f6bce2018-09-19 13:12:31 -070021abbreviated object name of the most recent commit. The result
22is a "human-readable" object name which can also be used to
23identify the commit to other git commands.
Junio C Hamanoc06818e2005-12-27 16:10:56 -080024
Shawn O. Pearce7e425c42008-10-13 07:39:46 -070025By default (without --all or --tags) `git describe` only shows
26annotated tags. For more information about creating annotated tags
27see the -a and -s options to linkgit:git-tag[1].
Junio C Hamanoc06818e2005-12-27 16:10:56 -080028
Stefan Beller644eb602017-11-15 18:00:39 -080029If the given object refers to a blob, it will be described
30as `<commit-ish>:<path>`, such that the blob can be found
31at `<path>` in the `<commit-ish>`, which itself describes the
32first commit in which this blob occurs in a reverse revision walk
33from HEAD.
34
Junio C Hamanoc06818e2005-12-27 16:10:56 -080035OPTIONS
36-------
Richard Hansena8a54062013-09-04 15:04:31 -040037<commit-ish>...::
SZEDER Gábor2bd07062015-08-24 18:15:18 +020038 Commit-ish object names to describe. Defaults to HEAD if omitted.
Junio C Hamanoc06818e2005-12-27 16:10:56 -080039
Jean Privat9f67d2e2009-10-21 09:35:22 -040040--dirty[=<mark>]::
Stefan Bellerb0176ce2017-03-21 15:57:18 -070041--broken[=<mark>]::
42 Describe the state of the working tree. When the working
43 tree matches HEAD, the output is the same as "git describe
44 HEAD". If the working tree has local modification "-dirty"
45 is appended to it. If a repository is corrupt and Git
46 cannot determine if there is local modification, Git will
47 error out, unless `--broken' is given, which appends
48 the suffix "-broken" instead.
Jean Privat9f67d2e2009-10-21 09:35:22 -040049
Junio C Hamanoc06818e2005-12-27 16:10:56 -080050--all::
51 Instead of using only the annotated tags, use any ref
Junio C Hamano831e61f2012-08-06 13:36:47 -070052 found in `refs/` namespace. This option enables matching
Matthieu Moy29b9a662010-11-02 16:31:24 +010053 any known branch, remote-tracking branch, or lightweight tag.
Junio C Hamanoc06818e2005-12-27 16:10:56 -080054
55--tags::
56 Instead of using only the annotated tags, use any tag
Junio C Hamano831e61f2012-08-06 13:36:47 -070057 found in `refs/tags` namespace. This option enables matching
Shawn O. Pearce7e425c42008-10-13 07:39:46 -070058 a lightweight (non-annotated) tag.
Junio C Hamanoc06818e2005-12-27 16:10:56 -080059
Shawn O. Pearce23615702007-05-21 03:20:25 -040060--contains::
61 Instead of finding the tag that predates the commit, find
62 the tag that comes after the commit, and thus contains it.
63 Automatically implies --tags.
64
Junio C Hamanoc06818e2005-12-27 16:10:56 -080065--abbrev=<n>::
Anders Höckerstenbfe35a62021-05-17 05:53:50 +000066 Instead of using the default number of hexadecimal digits (which
67 will vary according to the number of objects in the repository with
68 a default of 7) of the abbreviated object name, use <n> digits, or
69 as many digits as needed to form a unique object name. An <n> of 0
Gisle Aas492cf3f2009-10-29 22:29:35 +010070 will suppress long format, only showing the closest tag.
Junio C Hamanoc06818e2005-12-27 16:10:56 -080071
Shawn O. Pearce8713ab32007-01-13 17:30:53 -050072--candidates=<n>::
73 Instead of considering only the 10 most recent tags as
Richard Hansena8a54062013-09-04 15:04:31 -040074 candidates to describe the input commit-ish consider
Shawn O. Pearce8713ab32007-01-13 17:30:53 -050075 up to <n> candidates. Increasing <n> above 10 will take
76 slightly longer but may produce a more accurate result.
Shawn O. Pearce2c33f752008-02-24 03:07:31 -050077 An <n> of 0 will cause only exact matches to be output.
78
79--exact-match::
80 Only output exact matches (a tag directly references the
81 supplied commit). This is a synonym for --candidates=0.
Shawn O. Pearce8713ab32007-01-13 17:30:53 -050082
83--debug::
84 Verbosely display information about the searching strategy
85 being employed to standard error. The tag name will still
86 be printed to standard out.
Junio C Hamanoc06818e2005-12-27 16:10:56 -080087
Santi Béjar518120e2008-02-25 10:43:33 +010088--long::
89 Always output the long format (the tag, the number of commits
90 and the abbreviated commit name) even when it matches a tag.
91 This is useful when you want to see parts of the commit object name
92 in "describe" output, even when the commit in question happens to be
93 a tagged version. Instead of just emitting the tag name, it will
Gisle Aas492cf3f2009-10-29 22:29:35 +010094 describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2
95 that points at object deadbee....).
Santi Béjar518120e2008-02-25 10:43:33 +010096
Pierre Habouzit30ffa602007-12-21 22:49:54 +010097--match <pattern>::
Greg Price52291492013-02-25 00:29:01 -050098 Only consider tags matching the given `glob(7)` pattern,
Max Kirillov6d68b2a2017-09-20 04:10:10 +030099 excluding the "refs/tags/" prefix. If used with `--all`, it also
100 considers local branches and remote-tracking references matching the
101 pattern, excluding respectively "refs/heads/" and "refs/remotes/"
102 prefix; references of other types are never considered. If given
103 multiple times, a list of patterns will be accumulated, and tags
104 matching any of the patterns will be considered. Use `--no-match` to
105 clear and reset the list of patterns.
Pierre Habouzit30ffa602007-12-21 22:49:54 +0100106
Jacob Keller77d21f22017-01-18 15:06:08 -0800107--exclude <pattern>::
108 Do not consider tags matching the given `glob(7)` pattern, excluding
Max Kirillov6d68b2a2017-09-20 04:10:10 +0300109 the "refs/tags/" prefix. If used with `--all`, it also does not consider
110 local branches and remote-tracking references matching the pattern,
111 excluding respectively "refs/heads/" and "refs/remotes/" prefix;
112 references of other types are never considered. If given multiple times,
113 a list of patterns will be accumulated and tags matching any of the
114 patterns will be excluded. When combined with --match a tag will be
115 considered when it matches at least one --match pattern and does not
Jacob Keller77d21f22017-01-18 15:06:08 -0800116 match any of the --exclude patterns. Use `--no-exclude` to clear and
117 reset the list of patterns.
118
Stephan Beyera3800f62008-06-08 03:36:11 +0200119--always::
120 Show uniquely abbreviated commit object as fallback.
121
Mike Crowee00dd1e2013-05-17 21:56:18 +0100122--first-parent::
123 Follow only the first parent commit upon seeing a merge commit.
124 This is useful when you wish to not match tags on branches merged
125 in the history of the target commit.
126
Junio C Hamanoc06818e2005-12-27 16:10:56 -0800127EXAMPLES
128--------
129
130With something like git.git current tree, I get:
131
Jonathan Niederb1889c32008-06-30 01:09:04 -0500132 [torvalds@g5 git]$ git describe parent
Junio C Hamano18912612007-01-26 23:24:07 -0800133 v1.0.4-14-g2414721
Junio C Hamanoc06818e2005-12-27 16:10:56 -0800134
135i.e. the current head of my "parent" branch is based on v1.0.4,
Jon Loeliger323b9db2009-01-12 14:02:07 -0600136but since it has a few commits on top of that,
Junio C Hamano18912612007-01-26 23:24:07 -0800137describe has added the number of additional commits ("14") and
138an abbreviated object name for the commit itself ("2414721")
139at the end.
140
141The number of additional commits is the number
142of commits which would be displayed by "git log v1.0.4..parent".
Linus Arver548afb02023-06-07 19:26:47 +0000143The hash suffix is "-g" + an unambiguous abbreviation for the tip commit
Anders Höckerstenbfe35a62021-05-17 05:53:50 +0000144of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). The
145length of the abbreviation scales as the repository grows, using the
146approximate number of objects in the repository and a bit of math
147around the birthday paradox, and defaults to a minimum of 7.
Markus Heidelberg846b8f62010-03-22 21:45:33 +0100148The "g" prefix stands for "git" and is used to allow describing the version of
149a software depending on the SCM the software is managed with. This is useful
150in an environment where people may use different SCMs.
Junio C Hamanoc06818e2005-12-27 16:10:56 -0800151
Thomas Rast0b444cd2010-01-10 00:33:00 +0100152Doing a 'git describe' on a tag-name will just show the tag name:
Junio C Hamanoc06818e2005-12-27 16:10:56 -0800153
Jonathan Niederb1889c32008-06-30 01:09:04 -0500154 [torvalds@g5 git]$ git describe v1.0.4
Junio C Hamanoc06818e2005-12-27 16:10:56 -0800155 v1.0.4
156
157With --all, the command can use branch heads as references, so
158the output shows the reference path as well:
159
160 [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
Junio C Hamano18912612007-01-26 23:24:07 -0800161 tags/v1.0.0-21-g975b
Junio C Hamanoc06818e2005-12-27 16:10:56 -0800162
Gisle Aas492cf3f2009-10-29 22:29:35 +0100163 [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
Junio C Hamano18912612007-01-26 23:24:07 -0800164 heads/lt/describe-7-g975b
165
166With --abbrev set to 0, the command can be used to find the
167closest tagname without any suffix:
168
169 [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
170 tags/v1.0.0
Junio C Hamanoc06818e2005-12-27 16:10:56 -0800171
Gisle Aas492cf3f2009-10-29 22:29:35 +0100172Note that the suffix you get if you type these commands today may be
Gisle Aas0a565de2009-11-04 22:57:46 +0100173longer than what Linus saw above when he ran these commands, as your
Thomas Ackermann2de9b712013-01-21 20:17:53 +0100174Git repository may have new commits whose object names begin with
Gisle Aas492cf3f2009-10-29 22:29:35 +0100175975b that did not exist back then, and "-g975b" suffix alone may not
176be sufficient to disambiguate these commits.
177
178
Shawn O. Pearce8713ab32007-01-13 17:30:53 -0500179SEARCH STRATEGY
180---------------
181
Richard Hansena8a54062013-09-04 15:04:31 -0400182For each commit-ish supplied, 'git describe' will first look for
Shawn O. Pearce8713ab32007-01-13 17:30:53 -0500183a tag which tags exactly that commit. Annotated tags will always
184be preferred over lightweight tags, and tags with newer dates will
185always be preferred over tags with older dates. If an exact match
186is found, its name will be output and searching will stop.
187
Thomas Rast0b444cd2010-01-10 00:33:00 +0100188If an exact match was not found, 'git describe' will walk back
Shawn O. Pearce8713ab32007-01-13 17:30:53 -0500189through the commit history to locate an ancestor commit which
190has been tagged. The ancestor's tag will be output along with an
Matthieu Moybcf96262016-06-28 13:40:11 +0200191abbreviation of the input commit-ish's SHA-1. If `--first-parent` was
Mike Crowee00dd1e2013-05-17 21:56:18 +0100192specified then the walk will only consider the first parent of each
193commit.
Shawn O. Pearce8713ab32007-01-13 17:30:53 -0500194
195If multiple tags were found during the walk then the tag which
Richard Hansena8a54062013-09-04 15:04:31 -0400196has the fewest commits different from the input commit-ish will be
Shawn O. Pearce8713ab32007-01-13 17:30:53 -0500197selected and output. Here fewest commits different is defined as
Jonathan Nieder483bc4f2008-06-30 13:56:34 -0500198the number of commits which would be shown by `git log tag..input`
Shawn O. Pearce8713ab32007-01-13 17:30:53 -0500199will be the smallest number of commits possible.
200
Stefan Beller644eb602017-11-15 18:00:39 -0800201BUGS
202----
203
204Tree objects as well as tag objects not pointing at commits, cannot be described.
205When describing blobs, the lightweight tags pointing at blobs are ignored,
Linus Arver548afb02023-06-07 19:26:47 +0000206but the blob is still described as <commit-ish>:<path> despite the lightweight
Stefan Beller644eb602017-11-15 18:00:39 -0800207tag being favorable.
208
Junio C Hamanoc06818e2005-12-27 16:10:56 -0800209GIT
210---
Christian Couder9e1f0a82008-06-06 09:07:32 +0200211Part of the linkgit:git[1] suite