man1/git-describe.1

   1 .\"Generated by db2man.xsl. Don't modify this, modify the source.
   2 .de Sh \" Subsection
   3 .br
   4 .if t .Sp
   5 .ne 5
   6 .PP
   7 \fB\\$1\fR
   8 .PP
   9 ..
  10 .de Sp \" Vertical space (when we can't use .PP)
  11 .if t .sp .5v
  12 .if n .sp
  13 ..
  14 .de Ip \" List item
  15 .br
  16 .ie \\n(.$>=3 .ne \\$3
  17 .el .ne 3
  18 .IP "\\$1" \\$2
  19 ..
  20 .TH "GIT-DESCRIBE" 1 "" "" ""
  21 .SH NAME
  22 git-describe \- Show the most recent tag that is reachable from a commit
  23 .SH "SYNOPSIS"
  24
  25
  26 \fIgit\-describe\fR [\-\-all] [\-\-tags] [\-\-abbrev=<n>] <committish>...
  27
  28 .SH "DESCRIPTION"
  29
  30
  31 The command finds the most recent tag that is reachable from a commit, and if the commit itself is pointed at by the tag, shows the tag\&. Otherwise, it suffixes the tag name with abbreviated object name of the commit\&.
  32
  33 .SH "OPTIONS"
  34
  35 .TP
  36 <committish>
  37 The object name of the comittish\&.
  38
  39 .TP
  40 \-\-all
  41 Instead of using only the annotated tags, use any ref found in \&.git/refs/\&.
  42
  43 .TP
  44 \-\-tags
  45 Instead of using only the annotated tags, use any tag found in \&.git/refs/tags\&.
  46
  47 .TP
  48 \-\-abbrev=<n>
  49 Instead of using the default 8 hexadecimal digits as the abbreviated object name, use <n> digits\&.
  50
  51 .SH "EXAMPLES"
  52
  53
  54 With something like git\&.git current tree, I get:
  55
  56 .nf
  57 [torvalds@g5 git]$ git\-describe parent
  58 v1\&.0\&.4\-g2414721b
  59 .fi
  60
  61
  62 i\&.e\&. the current head of my "parent" branch is based on v1\&.0\&.4, but since it has a few commits on top of that, it has added the git hash of the thing to the end: "\-g" + 8\-char shorthand for the commit 2414721b194453f058079d897d13c4e377f92dc6\&.
  63
  64
  65 Doing a "git\-describe" on a tag\-name will just show the tag name:
  66
  67 .nf
  68 [torvalds@g5 git]$ git\-describe v1\&.0\&.4
  69 v1\&.0\&.4
  70 .fi
  71
  72
  73 With \-\-all, the command can use branch heads as references, so the output shows the reference path as well:
  74
  75 .nf
  76 [torvalds@g5 git]$ git describe \-\-all \-\-abbrev=4 v1\&.0\&.5^2
  77 tags/v1\&.0\&.0\-g975b
  78 .fi
  79
  80 .nf
  81 [torvalds@g5 git]$ git describe \-\-all HEAD^
  82 heads/lt/describe\-g975b
  83 .fi
  84
  85 .SH "AUTHOR"
  86
  87
  88 Written by Linus Torvalds <torvalds@osdl\&.org>, but somewhat butchered by Junio C Hamano <junkio@cox\&.net>
  89
  90 .SH "DOCUMENTATION"
  91
  92
  93 Documentation by David Greaves, Junio C Hamano and the git\-list <git@vger\&.kernel\&.org>\&.
  94
  95 .SH "GIT"
  96
  97
  98 Part of the \fBgit\fR(7) suite
  99