doc/source/en/TortoiseGit/git_doc/git-tag.html.xml

   1 <?xml version="1.0" encoding="UTF-8"?>\r
   2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN" "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">\r
   3 \r
   4 <article lang="en" id="git-tag(1)">\r
   5 <articleinfo>\r
   6     <title>git-tag(1)</title>\r
   7         <indexterm>\r
   8                 <primary>git-tag(1)</primary>\r
   9         </indexterm>\r
  10 </articleinfo>\r
  11 <simplesect id="_name">\r
  12 <title>NAME</title>\r
  13 <simpara>git-tag - Create, list, delete or verify a tag object signed with GPG</simpara>\r
  14 </simplesect>\r
  15 <simplesect id="_synopsis">\r
  16 <title>SYNOPSIS</title>\r
  17 <blockquote>\r
  18 <literallayout><emphasis>git tag</emphasis> [-a | -s | -u &lt;key-id&gt;] [-f] [-m &lt;msg&gt; | -F &lt;file&gt;]\r
  19         &lt;name&gt; [&lt;commit&gt; | &lt;object&gt;]\r
  20 <emphasis>git tag</emphasis> -d &lt;name&gt;&#8230;\r
  21 <emphasis>git tag</emphasis> [-n[&lt;num&gt;]] -l [--contains &lt;commit&gt;] [&lt;pattern&gt;]\r
  22 <emphasis>git tag</emphasis> -v &lt;name&gt;&#8230;</literallayout>\r
  23 </blockquote>\r
  24 </simplesect>\r
  25 <simplesect id="_description">\r
  26 <title>DESCRIPTION</title>\r
  27 <simpara>Adds a <emphasis>tag</emphasis> reference in <literal>.git/refs/tags/</literal></simpara>\r
  28 <simpara>Unless <literal>-f</literal> is given, the tag must not yet exist in\r
  29 <literal>.git/refs/tags/</literal> directory.</simpara>\r
  30 <simpara>If one of <literal>-a</literal>, <literal>-s</literal>, or <literal>-u &lt;key-id&gt;</literal> is passed, the command\r
  31 creates a <emphasis>tag</emphasis> object, and requires the tag message.  Unless\r
  32 <literal>-m &lt;msg&gt;</literal> or <literal>-F &lt;file&gt;</literal> is given, an editor is started for the user to type\r
  33 in the tag message.</simpara>\r
  34 <simpara>If <literal>-m &lt;msg&gt;</literal> or <literal>-F &lt;file&gt;</literal> is given and <literal>-a</literal>, <literal>-s</literal>, and <literal>-u &lt;key-id&gt;</literal>\r
  35 are absent, <literal>-a</literal> is implied.</simpara>\r
  36 <simpara>Otherwise just the SHA1 object name of the commit object is\r
  37 written (i.e. a lightweight tag).</simpara>\r
  38 <simpara>A GnuPG signed tag object will be created when <literal>-s</literal> or <literal>-u\r
  39 &lt;key-id&gt;</literal> is used.  When <literal>-u &lt;key-id&gt;</literal> is not used, the\r
  40 committer identity for the current user is used to find the\r
  41 GnuPG key for signing.</simpara>\r
  42 </simplesect>\r
  43 <simplesect id="_options">\r
  44 <title>OPTIONS</title>\r
  45 <variablelist>\r
  46 <varlistentry>\r
  47 <term>\r
  48 -a\r
  49 </term>\r
  50 <listitem>\r
  51 <simpara>\r
  52         Make an unsigned, annotated tag object\r
  53 </simpara>\r
  54 </listitem>\r
  55 </varlistentry>\r
  56 <varlistentry>\r
  57 <term>\r
  58 -s\r
  59 </term>\r
  60 <listitem>\r
  61 <simpara>\r
  62         Make a GPG-signed tag, using the default e-mail address&#8217;s key\r
  63 </simpara>\r
  64 </listitem>\r
  65 </varlistentry>\r
  66 <varlistentry>\r
  67 <term>\r
  68 -u &lt;key-id&gt;\r
  69 </term>\r
  70 <listitem>\r
  71 <simpara>\r
  72         Make a GPG-signed tag, using the given key\r
  73 </simpara>\r
  74 </listitem>\r
  75 </varlistentry>\r
  76 <varlistentry>\r
  77 <term>\r
  78 -f\r
  79 </term>\r
  80 <listitem>\r
  81 <simpara>\r
  82         Replace an existing tag with the given name (instead of failing)\r
  83 </simpara>\r
  84 </listitem>\r
  85 </varlistentry>\r
  86 <varlistentry>\r
  87 <term>\r
  88 -d\r
  89 </term>\r
  90 <listitem>\r
  91 <simpara>\r
  92         Delete existing tags with the given names.\r
  93 </simpara>\r
  94 </listitem>\r
  95 </varlistentry>\r
  96 <varlistentry>\r
  97 <term>\r
  98 -v\r
  99 </term>\r
 100 <listitem>\r
 101 <simpara>\r
 102         Verify the gpg signature of the given tag names.\r
 103 </simpara>\r
 104 </listitem>\r
 105 </varlistentry>\r
 106 <varlistentry>\r
 107 <term>\r
 108 -n&lt;num&gt;\r
 109 </term>\r
 110 <listitem>\r
 111 <simpara>\r
 112         &lt;num&gt; specifies how many lines from the annotation, if any,\r
 113         are printed when using -l.\r
 114         The default is not to print any annotation lines.\r
 115         If no number is given to <literal>-n</literal>, only the first line is printed.\r
 116 </simpara>\r
 117 </listitem>\r
 118 </varlistentry>\r
 119 <varlistentry>\r
 120 <term>\r
 121 -l &lt;pattern&gt;\r
 122 </term>\r
 123 <listitem>\r
 124 <simpara>\r
 125         List tags with names that match the given pattern (or all if no pattern is given).\r
 126         Typing "git tag" without arguments, also lists all tags.\r
 127 </simpara>\r
 128 </listitem>\r
 129 </varlistentry>\r
 130 <varlistentry>\r
 131 <term>\r
 132 --contains &lt;commit&gt;\r
 133 </term>\r
 134 <listitem>\r
 135 <simpara>\r
 136         Only list tags which contain the specified commit.\r
 137 </simpara>\r
 138 </listitem>\r
 139 </varlistentry>\r
 140 <varlistentry>\r
 141 <term>\r
 142 -m &lt;msg&gt;\r
 143 </term>\r
 144 <listitem>\r
 145 <simpara>\r
 146         Use the given tag message (instead of prompting).\r
 147         If multiple <literal>-m</literal> options are given, their values are\r
 148         concatenated as separate paragraphs.\r
 149         Implies <literal>-a</literal> if none of <literal>-a</literal>, <literal>-s</literal>, or <literal>-u &lt;key-id&gt;</literal>\r
 150         is given.\r
 151 </simpara>\r
 152 </listitem>\r
 153 </varlistentry>\r
 154 <varlistentry>\r
 155 <term>\r
 156 -F &lt;file&gt;\r
 157 </term>\r
 158 <listitem>\r
 159 <simpara>\r
 160         Take the tag message from the given file.  Use <emphasis>-</emphasis> to\r
 161         read the message from the standard input.\r
 162         Implies <literal>-a</literal> if none of <literal>-a</literal>, <literal>-s</literal>, or <literal>-u &lt;key-id&gt;</literal>\r
 163         is given.\r
 164 </simpara>\r
 165 </listitem>\r
 166 </varlistentry>\r
 167 </variablelist>\r
 168 </simplesect>\r
 169 <simplesect id="_configuration">\r
 170 <title>CONFIGURATION</title>\r
 171 <simpara>By default, <emphasis>git-tag</emphasis> in sign-with-default mode (-s) will use your\r
 172 committer identity (of the form "Your Name &lt;<ulink url="mailto:your@email.address">your@email.address</ulink>&gt;") to\r
 173 find a key.  If you want to use a different default key, you can specify\r
 174 it in the repository configuration as follows:</simpara>\r
 175 <literallayout>[user]\r
 176     signingkey = &lt;gpg-key-id&gt;</literallayout>\r
 177 </simplesect>\r
 178 <simplesect id="_discussion">\r
 179 <title>DISCUSSION</title>\r
 180 <simplesect id="_on_re_tagging">\r
 181 <title>On Re-tagging</title>\r
 182 <simpara>What should you do when you tag a wrong commit and you would\r
 183 want to re-tag?</simpara>\r
 184 <simpara>If you never pushed anything out, just re-tag it. Use "-f" to\r
 185 replace the old one. And you&#8217;re done.</simpara>\r
 186 <simpara>But if you have pushed things out (or others could just read\r
 187 your repository directly), then others will have already seen\r
 188 the old tag. In that case you can do one of two things:</simpara>\r
 189 <orderedlist numeration="arabic">\r
 190 <listitem>\r
 191 <simpara>\r
 192 The sane thing.\r
 193 Just admit you screwed up, and use a different name. Others have\r
 194 already seen one tag-name, and if you keep the same name, you\r
 195 may be in the situation that two people both have "version X",\r
 196 but they actually have <emphasis>different</emphasis> "X"'s.  So just call it "X.1"\r
 197 and be done with it.\r
 198 </simpara>\r
 199 </listitem>\r
 200 <listitem>\r
 201 <simpara>\r
 202 The insane thing.\r
 203 You really want to call the new version "X" too, <emphasis>even though</emphasis>\r
 204 others have already seen the old one. So just use <emphasis>git-tag -f</emphasis>\r
 205 again, as if you hadn&#8217;t already published the old one.\r
 206 </simpara>\r
 207 </listitem>\r
 208 </orderedlist>\r
 209 <simpara>However, Git does <emphasis role="strong">not</emphasis> (and it should not) change tags behind\r
 210 users back. So if somebody already got the old tag, doing a\r
 211 <emphasis>git-pull</emphasis> on your tree shouldn&#8217;t just make them overwrite the old\r
 212 one.</simpara>\r
 213 <simpara>If somebody got a release tag from you, you cannot just change\r
 214 the tag for them by updating your own one. This is a big\r
 215 security issue, in that people MUST be able to trust their\r
 216 tag-names.  If you really want to do the insane thing, you need\r
 217 to just fess up to it, and tell people that you messed up. You\r
 218 can do that by making a very public announcement saying:</simpara>\r
 219 <literallayout>Ok, I messed up, and I pushed out an earlier version tagged as X. I\r
 220 then fixed something, and retagged the *fixed* tree as X again.\r
 221 \r
 222 If you got the wrong tag, and want the new one, please delete\r
 223 the old one and fetch the new one by doing:\r
 224 \r
 225         git tag -d X\r
 226         git fetch origin tag X\r
 227 \r
 228 to get my updated tag.\r
 229 \r
 230 You can test which tag you have by doing\r
 231 \r
 232         git rev-parse X\r
 233 \r
 234 which should return 0123456789abcdef.. if you have the new version.\r
 235 \r
 236 Sorry for inconvenience.</literallayout>\r
 237 <simpara>Does this seem a bit complicated?  It <emphasis role="strong">should</emphasis> be. There is no\r
 238 way that it would be correct to just "fix" it behind peoples\r
 239 backs. People need to know that their tags might have been\r
 240 changed.</simpara>\r
 241 </simplesect>\r
 242 <simplesect id="_on_automatic_following">\r
 243 <title>On Automatic following</title>\r
 244 <simpara>If you are following somebody else&#8217;s tree, you are most likely\r
 245 using tracking branches (<literal>refs/heads/origin</literal> in traditional\r
 246 layout, or <literal>refs/remotes/origin/master</literal> in the separate-remote\r
 247 layout).  You usually want the tags from the other end.</simpara>\r
 248 <simpara>On the other hand, if you are fetching because you would want a\r
 249 one-shot merge from somebody else, you typically do not want to\r
 250 get tags from there.  This happens more often for people near\r
 251 the toplevel but not limited to them.  Mere mortals when pulling\r
 252 from each other do not necessarily want to automatically get\r
 253 private anchor point tags from the other person.</simpara>\r
 254 <simpara>You would notice "please pull" messages on the mailing list says\r
 255 repo URL and branch name alone.  This is designed to be easily\r
 256 cut&amp;pasted to a <emphasis>git-fetch</emphasis> command line:</simpara>\r
 257 <literallayout>Linus, please pull from\r
 258 \r
 259         git://git..../proj.git master\r
 260 \r
 261 to get the following updates...</literallayout>\r
 262 <simpara>becomes:</simpara>\r
 263 <literallayout>$ git pull git://git..../proj.git master</literallayout>\r
 264 <simpara>In such a case, you do not want to automatically follow other&#8217;s\r
 265 tags.</simpara>\r
 266 <simpara>One important aspect of git is it is distributed, and being\r
 267 distributed largely means there is no inherent "upstream" or\r
 268 "downstream" in the system.  On the face of it, the above\r
 269 example might seem to indicate that the tag namespace is owned\r
 270 by upper echelon of people and tags only flow downwards, but\r
 271 that is not the case.  It only shows that the usage pattern\r
 272 determines who are interested in whose tags.</simpara>\r
 273 <simpara>A one-shot pull is a sign that a commit history is now crossing\r
 274 the boundary between one circle of people (e.g. "people who are\r
 275 primarily interested in the networking part of the kernel") who may\r
 276 have their own set of tags (e.g. "this is the third release\r
 277 candidate from the networking group to be proposed for general\r
 278 consumption with 2.6.21 release") to another circle of people\r
 279 (e.g. "people who integrate various subsystem improvements").\r
 280 The latter are usually not interested in the detailed tags used\r
 281 internally in the former group (that is what "internal" means).\r
 282 That is why it is desirable not to follow tags automatically in\r
 283 this case.</simpara>\r
 284 <simpara>It may well be that among networking people, they may want to\r
 285 exchange the tags internal to their group, but in that workflow\r
 286 they are most likely tracking with each other&#8217;s progress by\r
 287 having tracking branches.  Again, the heuristic to automatically\r
 288 follow such tags is a good thing.</simpara>\r
 289 </simplesect>\r
 290 <simplesect id="_on_backdating_tags">\r
 291 <title>On Backdating Tags</title>\r
 292 <simpara>If you have imported some changes from another VCS and would like\r
 293 to add tags for major releases of your work, it is useful to be able\r
 294 to specify the date to embed inside of the tag object.  The data in\r
 295 the tag object affects, for example, the ordering of tags in the\r
 296 gitweb interface.</simpara>\r
 297 <simpara>To set the date used in future tag objects, set the environment\r
 298 variable GIT_COMMITTER_DATE to one or more of the date and time.  The\r
 299 date and time can be specified in a number of ways; the most common\r
 300 is "YYYY-MM-DD HH:MM".</simpara>\r
 301 <simpara>An example follows.</simpara>\r
 302 <literallayout>$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1</literallayout>\r
 303 </simplesect>\r
 304 </simplesect>\r
 305 <simplesect id="_author">\r
 306 <title>Author</title>\r
 307 <simpara>Written by Linus Torvalds &lt;<ulink url="mailto:torvalds@osdl.org">torvalds@osdl.org</ulink>&gt;,\r
 308 Junio C Hamano &lt;<ulink url="mailto:gitster@pobox.com">gitster@pobox.com</ulink>&gt; and Chris Wright &lt;<ulink url="mailto:chrisw@osdl.org">chrisw@osdl.org</ulink>&gt;.</simpara>\r
 309 </simplesect>\r
 310 <simplesect id="_documentation">\r
 311 <title>Documentation</title>\r
 312 <simpara>Documentation by David Greaves, Junio C Hamano and the git-list &lt;<ulink url="mailto:git@vger.kernel.org">git@vger.kernel.org</ulink>&gt;.</simpara>\r
 313 </simplesect>\r
 314 <simplesect id="_git">\r
 315 <title>GIT</title>\r
 316 <simpara>Part of the <xref linkend="git(1)"/> suite</simpara>\r
 317 </simplesect>\r
 318 </article>\r