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 the 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 automatically.
 173 People need to know that their tags might have been changed.
 174
 175
 176 On Automatic following
 177 ~~~~~~~~~~~~~~~~~~~~~~
 178
 179 If you are following somebody else's tree, you are most likely
 180 using remote-tracking branches (`refs/heads/origin` in traditional
 181 layout, or `refs/remotes/origin/master` in the separate-remote
 182 layout).  You usually want the tags from the other end.
 183
 184 On the other hand, if you are fetching because you would want a
 185 one-shot merge from somebody else, you typically do not want to
 186 get tags from there.  This happens more often for people near
 187 the toplevel but not limited to them.  Mere mortals when pulling
 188 from each other do not necessarily want to automatically get
 189 private anchor point tags from the other person.
 190
 191 Often, "please pull" messages on the mailing list just provide
 192 two pieces of information: a repo URL and a branch name; this
 193 is designed to be easily cut&pasted at the end of a 'git fetch'
 194 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 the other
 211 person's tags.
 212
 213 One important aspect of git is its distributed nature, which
 214 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 the upper echelon of people and that 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 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; such 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 (see the later discussion of possible
 251 values; the most common form is "YYYY-MM-DD HH:MM").
 252
 253 For example:
 254
 255 ------------
 256 $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
 257 ------------
 258
 259 include::date-formats.txt[]
 260
 261 SEE ALSO
 262 --------
 263 linkgit:git-check-ref-format[1].
 264
 265 GIT
 266 ---
 267 Part of the linkgit:git[1] suite