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>] [--points-at <object>]
  16         [--column[=<options>] | --no-column] [<pattern>...]
  17 'git tag' -v <tagname>...
  18
  19 DESCRIPTION
  20 -----------
  21
  22 Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given
  23 to delete, list or verify tags.
  24
  25 Unless `-f` is given, the named tag must not yet exist.
  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 SHA-1 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.  The configuration variable `gpg.program`
  42 is used to specify custom GnuPG binary.
  43
  44 Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated"
  45 tags; they contain a creation date, the tagger name and e-mail, a
  46 tagging message, and an optional GnuPG signature. Whereas a
  47 "lightweight" tag is simply a name for an object (usually a commit
  48 object).
  49
  50 Annotated tags are meant for release while lightweight tags are meant
  51 for private or temporary object labels. For this reason, some git
  52 commands for naming objects (like `git describe`) will ignore
  53 lightweight tags by default.
  54
  55
  56 OPTIONS
  57 -------
  58 -a::
  59 --annotate::
  60         Make an unsigned, annotated tag object
  61
  62 -s::
  63 --sign::
  64         Make a GPG-signed tag, using the default e-mail address's key.
  65
  66 -u <key-id>::
  67 --local-user=<key-id>::
  68         Make a GPG-signed tag, using the given key.
  69
  70 -f::
  71 --force::
  72         Replace an existing tag with the given name (instead of failing)
  73
  74 -d::
  75 --delete::
  76         Delete existing tags with the given names.
  77
  78 -v::
  79 --verify::
  80         Verify the gpg signature of the given tag names.
  81
  82 -n<num>::
  83         <num> specifies how many lines from the annotation, if any,
  84         are printed when using -l.
  85         The default is not to print any annotation lines.
  86         If no number is given to `-n`, only the first line is printed.
  87         If the tag is not annotated, the commit message is displayed instead.
  88
  89 -l <pattern>::
  90 --list <pattern>::
  91         List tags with names that match the given pattern (or all if no
  92         pattern is given).  Running "git tag" without arguments also
  93         lists all tags. The pattern is a shell wildcard (i.e., matched
  94         using fnmatch(3)).  Multiple patterns may be given; if any of
  95         them matches, the tag is shown.
  96
  97 --sort=<type>::
  98         Sort in a specific order. Supported type is "refname"
  99         (lexicographic order), "version:refname" or "v:refname" (tag
 100         names are treated as versions). Prepend "-" to reverse sort
 101         order. When this option is not given, the sort order defaults to the
 102         value configured for the 'tag.sort' variable if it exists, or
 103         lexicographic order otherwise. See linkgit:git-config[1].
 104
 105 --column[=<options>]::
 106 --no-column::
 107         Display tag listing in columns. See configuration variable
 108         column.tag for option syntax.`--column` and `--no-column`
 109         without options are equivalent to 'always' and 'never' respectively.
 110 +
 111 This option is only applicable when listing tags without annotation lines.
 112
 113 --contains [<commit>]::
 114         Only list tags which contain the specified commit (HEAD if not
 115         specified).
 116
 117 --points-at <object>::
 118         Only list tags of the given object.
 119
 120 -m <msg>::
 121 --message=<msg>::
 122         Use the given tag message (instead of prompting).
 123         If multiple `-m` options are given, their values are
 124         concatenated as separate paragraphs.
 125         Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
 126         is given.
 127
 128 -F <file>::
 129 --file=<file>::
 130         Take the tag message from the given file.  Use '-' to
 131         read the message from the standard input.
 132         Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
 133         is given.
 134
 135 --cleanup=<mode>::
 136         This option sets how the tag message is cleaned up.
 137         The  '<mode>' can be one of 'verbatim', 'whitespace' and 'strip'.  The
 138         'strip' mode is default. The 'verbatim' mode does not change message at
 139         all, 'whitespace' removes just leading/trailing whitespace lines and
 140         'strip' removes both whitespace and commentary.
 141
 142 <tagname>::
 143         The name of the tag to create, delete, or describe.
 144         The new tag name must pass all checks defined by
 145         linkgit:git-check-ref-format[1].  Some of these checks
 146         may restrict the characters allowed in a tag name.
 147
 148 <commit>::
 149 <object>::
 150         The object that the new tag will refer to, usually a commit.
 151         Defaults to HEAD.
 152
 153
 154 CONFIGURATION
 155 -------------
 156 By default, 'git tag' in sign-with-default mode (-s) will use your
 157 committer identity (of the form "Your Name <\your@email.address>") to
 158 find a key.  If you want to use a different default key, you can specify
 159 it in the repository configuration as follows:
 160
 161 -------------------------------------
 162 [user]
 163     signingkey = <gpg-key-id>
 164 -------------------------------------
 165
 166
 167 DISCUSSION
 168 ----------
 169
 170 On Re-tagging
 171 ~~~~~~~~~~~~~
 172
 173 What should you do when you tag a wrong commit and you would
 174 want to re-tag?
 175
 176 If you never pushed anything out, just re-tag it. Use "-f" to
 177 replace the old one. And you're done.
 178
 179 But if you have pushed things out (or others could just read
 180 your repository directly), then others will have already seen
 181 the old tag. In that case you can do one of two things:
 182
 183 . The sane thing.
 184 Just admit you screwed up, and use a different name. Others have
 185 already seen one tag-name, and if you keep the same name, you
 186 may be in the situation that two people both have "version X",
 187 but they actually have 'different' "X"'s.  So just call it "X.1"
 188 and be done with it.
 189
 190 . The insane thing.
 191 You really want to call the new version "X" too, 'even though'
 192 others have already seen the old one. So just use 'git tag -f'
 193 again, as if you hadn't already published the old one.
 194
 195 However, Git does *not* (and it should not) change tags behind
 196 users back. So if somebody already got the old tag, doing a
 197 'git pull' on your tree shouldn't just make them overwrite the old
 198 one.
 199
 200 If somebody got a release tag from you, you cannot just change
 201 the tag for them by updating your own one. This is a big
 202 security issue, in that people MUST be able to trust their
 203 tag-names.  If you really want to do the insane thing, you need
 204 to just fess up to it, and tell people that you messed up. You
 205 can do that by making a very public announcement saying:
 206
 207 ------------
 208 Ok, I messed up, and I pushed out an earlier version tagged as X. I
 209 then fixed something, and retagged the *fixed* tree as X again.
 210
 211 If you got the wrong tag, and want the new one, please delete
 212 the old one and fetch the new one by doing:
 213
 214         git tag -d X
 215         git fetch origin tag X
 216
 217 to get my updated tag.
 218
 219 You can test which tag you have by doing
 220
 221         git rev-parse X
 222
 223 which should return 0123456789abcdef.. if you have the new version.
 224
 225 Sorry for the inconvenience.
 226 ------------
 227
 228 Does this seem a bit complicated?  It *should* be. There is no
 229 way that it would be correct to just "fix" it automatically.
 230 People need to know that their tags might have been changed.
 231
 232
 233 On Automatic following
 234 ~~~~~~~~~~~~~~~~~~~~~~
 235
 236 If you are following somebody else's tree, you are most likely
 237 using remote-tracking branches (`refs/heads/origin` in traditional
 238 layout, or `refs/remotes/origin/master` in the separate-remote
 239 layout).  You usually want the tags from the other end.
 240
 241 On the other hand, if you are fetching because you would want a
 242 one-shot merge from somebody else, you typically do not want to
 243 get tags from there.  This happens more often for people near
 244 the toplevel but not limited to them.  Mere mortals when pulling
 245 from each other do not necessarily want to automatically get
 246 private anchor point tags from the other person.
 247
 248 Often, "please pull" messages on the mailing list just provide
 249 two pieces of information: a repo URL and a branch name; this
 250 is designed to be easily cut&pasted at the end of a 'git fetch'
 251 command line:
 252
 253 ------------
 254 Linus, please pull from
 255
 256         git://git..../proj.git master
 257
 258 to get the following updates...
 259 ------------
 260
 261 becomes:
 262
 263 ------------
 264 $ git pull git://git..../proj.git master
 265 ------------
 266
 267 In such a case, you do not want to automatically follow the other
 268 person's tags.
 269
 270 One important aspect of Git is its distributed nature, which
 271 largely means there is no inherent "upstream" or
 272 "downstream" in the system.  On the face of it, the above
 273 example might seem to indicate that the tag namespace is owned
 274 by the upper echelon of people and that tags only flow downwards, but
 275 that is not the case.  It only shows that the usage pattern
 276 determines who are interested in whose tags.
 277
 278 A one-shot pull is a sign that a commit history is now crossing
 279 the boundary between one circle of people (e.g. "people who are
 280 primarily interested in the networking part of the kernel") who may
 281 have their own set of tags (e.g. "this is the third release
 282 candidate from the networking group to be proposed for general
 283 consumption with 2.6.21 release") to another circle of people
 284 (e.g. "people who integrate various subsystem improvements").
 285 The latter are usually not interested in the detailed tags used
 286 internally in the former group (that is what "internal" means).
 287 That is why it is desirable not to follow tags automatically in
 288 this case.
 289
 290 It may well be that among networking people, they may want to
 291 exchange the tags internal to their group, but in that workflow
 292 they are most likely tracking each other's progress by
 293 having remote-tracking branches.  Again, the heuristic to automatically
 294 follow such tags is a good thing.
 295
 296
 297 On Backdating Tags
 298 ~~~~~~~~~~~~~~~~~~
 299
 300 If you have imported some changes from another VCS and would like
 301 to add tags for major releases of your work, it is useful to be able
 302 to specify the date to embed inside of the tag object; such data in
 303 the tag object affects, for example, the ordering of tags in the
 304 gitweb interface.
 305
 306 To set the date used in future tag objects, set the environment
 307 variable GIT_COMMITTER_DATE (see the later discussion of possible
 308 values; the most common form is "YYYY-MM-DD HH:MM").
 309
 310 For example:
 311
 312 ------------
 313 $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
 314 ------------
 315
 316 include::date-formats.txt[]
 317
 318 SEE ALSO
 319 --------
 320 linkgit:git-check-ref-format[1].
 321 linkgit:git-config[1].
 322
 323 GIT
 324 ---
 325 Part of the linkgit:git[1] suite