1git-describe(1) 2=============== 3 4NAME 5---- 6git-describe - Show the most recent tag that is reachable from a commit 7 8 9SYNOPSIS 10-------- 11'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] <committish>... 12 13DESCRIPTION 14----------- 15The command finds the most recent tag that is reachable from a 16commit. If the tag points to the commit, then only the tag is 17shown. Otherwise, it suffixes the tag name with the number of 18additional commits on top of the tagged object and the 19abbreviated object name of the most recent commit. 20 21By default (without --all or --tags) `git describe` only shows 22annotated tags. For more information about creating annotated tags 23see the -a and -s options to linkgit:git-tag[1]. 24 25OPTIONS 26------- 27<committish>...:: 28 Committish object names to describe. 29 30--all:: 31 Instead of using only the annotated tags, use any ref 32 found in `.git/refs/`. This option enables matching 33 any known branch, remote branch, or lightweight tag. 34 35--tags:: 36 Instead of using only the annotated tags, use any tag 37 found in `.git/refs/tags`. This option enables matching 38 a lightweight (non-annotated) tag. 39 40--contains:: 41 Instead of finding the tag that predates the commit, find 42 the tag that comes after the commit, and thus contains it. 43 Automatically implies --tags. 44 45--abbrev=<n>:: 46 Instead of using the default 7 hexadecimal digits as the 47 abbreviated object name, use <n> digits, or as many digits 48 as needed to form a unique object name. An <n> of 0 49 will suppress long format, only showing the closest tag. 50 51--candidates=<n>:: 52 Instead of considering only the 10 most recent tags as 53 candidates to describe the input committish consider 54 up to <n> candidates. Increasing <n> above 10 will take 55 slightly longer but may produce a more accurate result. 56 An <n> of 0 will cause only exact matches to be output. 57 58--exact-match:: 59 Only output exact matches (a tag directly references the 60 supplied commit). This is a synonym for --candidates=0. 61 62--debug:: 63 Verbosely display information about the searching strategy 64 being employed to standard error. The tag name will still 65 be printed to standard out. 66 67--long:: 68 Always output the long format (the tag, the number of commits 69 and the abbreviated commit name) even when it matches a tag. 70 This is useful when you want to see parts of the commit object name 71 in "describe" output, even when the commit in question happens to be 72 a tagged version. Instead of just emitting the tag name, it will 73 describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2 74 that points at object deadbee....). 75 76--match <pattern>:: 77 Only consider tags matching the given pattern (can be used to avoid 78 leaking private tags made from the repository). 79 80--always:: 81 Show uniquely abbreviated commit object as fallback. 82 83EXAMPLES 84-------- 85 86With something like git.git current tree, I get: 87 88 [torvalds@g5 git]$ git describe parent 89 v1.0.4-14-g2414721 90 91i.e. the current head of my "parent" branch is based on v1.0.4, 92but since it has a few commits on top of that, 93describe has added the number of additional commits ("14") and 94an abbreviated object name for the commit itself ("2414721") 95at the end. 96 97The number of additional commits is the number 98of commits which would be displayed by "git log v1.0.4..parent". 99The hash suffix is "-g" + 7-char abbreviation for the tip commit 100of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`). 101 102Doing a 'git-describe' on a tag-name will just show the tag name: 103 104 [torvalds@g5 git]$ git describe v1.0.4 105 v1.0.4 106 107With --all, the command can use branch heads as references, so 108the output shows the reference path as well: 109 110 [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2 111 tags/v1.0.0-21-g975b 112 113 [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^ 114 heads/lt/describe-7-g975b 115 116With --abbrev set to 0, the command can be used to find the 117closest tagname without any suffix: 118 119 [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2 120 tags/v1.0.0 121 122Note that the suffix you get if you type these commands today may be 123longer than what Linus saw above when he ran these commands, as your 124git repository may have new commits whose object names begin with 125975b that did not exist back then, and "-g975b" suffix alone may not 126be sufficient to disambiguate these commits. 127 128 129SEARCH STRATEGY 130--------------- 131 132For each committish supplied, 'git-describe' will first look for 133a tag which tags exactly that commit. Annotated tags will always 134be preferred over lightweight tags, and tags with newer dates will 135always be preferred over tags with older dates. If an exact match 136is found, its name will be output and searching will stop. 137 138If an exact match was not found, 'git-describe' will walk back 139through the commit history to locate an ancestor commit which 140has been tagged. The ancestor's tag will be output along with an 141abbreviation of the input committish's SHA1. 142 143If multiple tags were found during the walk then the tag which 144has the fewest commits different from the input committish will be 145selected and output. Here fewest commits different is defined as 146the number of commits which would be shown by `git log tag..input` 147will be the smallest number of commits possible. 148 149 150Author 151------ 152Written by Linus Torvalds <torvalds@osdl.org>, but somewhat 153butchered by Junio C Hamano <gitster@pobox.com>. Later significantly 154updated by Shawn Pearce <spearce@spearce.org>. 155 156Documentation 157-------------- 158Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. 159 160GIT 161--- 162Part of the linkgit:git[1] suite