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