Documentation/git-describe.txt

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