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