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