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