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] [--abbrev=<n>] <committish>...
  12
  13 DESCRIPTION
  14 -----------
  15 The command finds the most recent tag that is reachable from a
  16 commit, and if the commit itself is pointed at by the tag, shows
  17 the tag.  Otherwise, it suffixes the tag name with abbreviated
  18 object name of the commit.
  19
  20
  21 OPTIONS
  22 -------
  23 <committish>::
  24         The object name of the comittish.
  25
  26 --all::
  27         Instead of using only the annotated tags, use any ref
  28         found in `.git/refs/`.
  29
  30 --tags::
  31         Instead of using only the annotated tags, use any tag
  32         found in `.git/refs/tags`.
  33
  34 --abbrev=<n>::
  35         Instead of using the default 8 hexadecimal digits as the
  36         abbreviated object name, use <n> digits.
  37
  38
  39 EXAMPLES
  40 --------
  41
  42 With something like git.git current tree, I get:
  43
  44         [torvalds@g5 git]$ git-describe parent
  45         v1.0.4-g2414721b
  46
  47 i.e. the current head of my "parent" branch is based on v1.0.4,
  48 but since it has a few commits on top of that, it has added the
  49 git hash of the thing to the end: "-g" + 8-char shorthand for
  50 the commit `2414721b194453f058079d897d13c4e377f92dc6`.
  51
  52 Doing a "git-describe" on a tag-name will just show the tag name:
  53
  54         [torvalds@g5 git]$ git-describe v1.0.4
  55         v1.0.4
  56
  57 With --all, the command can use branch heads as references, so
  58 the output shows the reference path as well:
  59
  60         [torvalds@g5 git]$ git describe --all --abbrev=4 v1.0.5^2
  61         tags/v1.0.0-g975b
  62
  63         [torvalds@g5 git]$ git describe --all HEAD^
  64         heads/lt/describe-g975b
  65
  66
  67 Author
  68 ------
  69 Written by Linus Torvalds <torvalds@osdl.org>, but somewhat
  70 butchered by Junio C Hamano <junkio@cox.net>
  71
  72 Documentation
  73 --------------
  74 Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>.
  75
  76 GIT
  77 ---
  78 Part of the gitlink:git[7] suite
  79