Documentation/git-tag.txt

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