Documentation/git-describe.txt

   1 git-describe(1)
   2 ===============
   3
   4 NAME
   5 ----
   6 git-describe - Give an object a human readable name based on an available ref
   7
   8 SYNOPSIS
   9 --------
  10 [verse]
  11 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] [<commit-ish>...]
  12 'git describe' [--all] [--tags] [--contains] [--abbrev=<n>] --dirty[=<mark>]
  13 'git describe' <blob>
  14
  15 DESCRIPTION
  16 -----------
  17 The command finds the most recent tag that is reachable from a
  18 commit.  If the tag points to the commit, then only the tag is
  19 shown.  Otherwise, it suffixes the tag name with the number of
  20 additional commits on top of the tagged object and the
  21 abbreviated object name of the most recent commit.
  22
  23 By default (without --all or --tags) `git describe` only shows
  24 annotated tags.  For more information about creating annotated tags
  25 see the -a and -s options to linkgit:git-tag[1].
  26
  27 If the given object refers to a blob, it will be described
  28 as `<commit-ish>:<path>`, such that the blob can be found
  29 at `<path>` in the `<commit-ish>`, which itself describes the
  30 first commit in which this blob occurs in a reverse revision walk
  31 from HEAD.
  32
  33 OPTIONS
  34 -------
  35 <commit-ish>...::
  36         Commit-ish object names to describe.  Defaults to HEAD if omitted.
  37
  38 --dirty[=<mark>]::
  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.
  47
  48 --all::
  49         Instead of using only the annotated tags, use any ref
  50         found in `refs/` namespace.  This option enables matching
  51         any known branch, remote-tracking branch, or lightweight tag.
  52
  53 --tags::
  54         Instead of using only the annotated tags, use any tag
  55         found in `refs/tags` namespace.  This option enables matching
  56         a lightweight (non-annotated) tag.
  57
  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
  63 --abbrev=<n>::
  64         Instead of using the default 7 hexadecimal digits as the
  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.
  68
  69 --candidates=<n>::
  70         Instead of considering only the 10 most recent tags as
  71         candidates to describe the input commit-ish consider
  72         up to <n> candidates.  Increasing <n> above 10 will take
  73         slightly longer but may produce a more accurate result.
  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.
  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.
  84
  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
  91         describe such a commit as v1.2-0-gdeadbee (0th commit since tag v1.2
  92         that points at object deadbee....).
  93
  94 --match <pattern>::
  95         Only consider tags matching the given `glob(7)` pattern,
  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.
 103
 104 --exclude <pattern>::
 105         Do not consider tags matching the given `glob(7)` pattern, excluding
 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
 113         match any of the --exclude patterns. Use `--no-exclude` to clear and
 114         reset the list of patterns.
 115
 116 --always::
 117         Show uniquely abbreviated commit object as fallback.
 118
 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
 124 EXAMPLES
 125 --------
 126
 127 With something like git.git current tree, I get:
 128
 129         [torvalds@g5 git]$ git describe parent
 130         v1.0.4-14-g2414721
 131
 132 i.e. the current head of my "parent" branch is based on v1.0.4,
 133 but since it has a few commits on top of that,
 134 describe has added the number of additional commits ("14") and
 135 an abbreviated object name for the commit itself ("2414721")
 136 at the end.
 137
 138 The number of additional commits is the number
 139 of commits which would be displayed by "git log v1.0.4..parent".
 140 The hash suffix is "-g" + 7-char abbreviation for the tip commit
 141 of parent (which was `2414721b194453f058079d897d13c4e377f92dc6`).
 142 The "g" prefix stands for "git" and is used to allow describing the version of
 143 a software depending on the SCM the software is managed with. This is useful
 144 in an environment where people may use different SCMs.
 145
 146 Doing a 'git describe' on a tag-name will just show the tag name:
 147
 148         [torvalds@g5 git]$ git describe v1.0.4
 149         v1.0.4
 150
 151 With --all, the command can use branch heads as references, so
 152 the output shows the reference path as well:
 153
 154         [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
 155         tags/v1.0.0-21-g975b
 156
 157         [torvalds@g5 git]$ git describe --all --abbrev=4 HEAD^
 158         heads/lt/describe-7-g975b
 159
 160 With --abbrev set to 0, the command can be used to find the
 161 closest tagname without any suffix:
 162
 163         [torvalds@g5 git]$ git describe --abbrev=0 v1.0.5^2
 164         tags/v1.0.0
 165
 166 Note that the suffix you get if you type these commands today may be
 167 longer than what Linus saw above when he ran these commands, as your
 168 Git repository may have new commits whose object names begin with
 169 975b that did not exist back then, and "-g975b" suffix alone may not
 170 be sufficient to disambiguate these commits.
 171
 172
 173 SEARCH STRATEGY
 174 ---------------
 175
 176 For each commit-ish supplied, 'git describe' will first look for
 177 a tag which tags exactly that commit.  Annotated tags will always
 178 be preferred over lightweight tags, and tags with newer dates will
 179 always be preferred over tags with older dates.  If an exact match
 180 is found, its name will be output and searching will stop.
 181
 182 If an exact match was not found, 'git describe' will walk back
 183 through the commit history to locate an ancestor commit which
 184 has been tagged.  The ancestor's tag will be output along with an
 185 abbreviation of the input commit-ish's SHA-1. If `--first-parent` was
 186 specified then the walk will only consider the first parent of each
 187 commit.
 188
 189 If multiple tags were found during the walk then the tag which
 190 has the fewest commits different from the input commit-ish will be
 191 selected and output.  Here fewest commits different is defined as
 192 the number of commits which would be shown by `git log tag..input`
 193 will be the smallest number of commits possible.
 194
 195 BUGS
 196 ----
 197
 198 Tree objects as well as tag objects not pointing at commits, cannot be described.
 199 When describing blobs, the lightweight tags pointing at blobs are ignored,
 200 but the blob is still described as <committ-ish>:<path> despite the lightweight
 201 tag being favorable.
 202
 203 GIT
 204 ---
 205 Part of the linkgit:git[1] suite