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