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