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 [<pattern>...] 17'git tag' -v <tagname>... 18 19DESCRIPTION 20----------- 21 22Add a tag reference in `.git/refs/tags/`, unless `-d/-l/-v` is given 23to delete, list or verify tags. 24 25Unless `-f` is given, the tag to be created must not yet exist in the 26`.git/refs/tags/` directory. 27 28If one of `-a`, `-s`, or `-u <key-id>` is passed, the command 29creates 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 31in the tag message. 32 33If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <key-id>` 34are absent, `-a` is implied. 35 36Otherwise just a tag reference for the SHA1 object name of the commit object is 37created (i.e. a lightweight tag). 38 39A GnuPG signed tag object will be created when `-s` or `-u 40<key-id>` is used. When `-u <key-id>` is not used, the 41committer identity for the current user is used to find the 42GnuPG key for signing. The configuration variable `gpg.program` 43is used to specify custom GnuPG binary. 44 45 46OPTIONS 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 121CONFIGURATION 122------------- 123By default, 'git tag' in sign-with-default mode (-s) will use your 124committer identity (of the form "Your Name <your@email.address>") to 125find a key. If you want to use a different default key, you can specify 126it in the repository configuration as follows: 127 128------------------------------------- 129[user] 130 signingkey = <gpg-key-id> 131------------------------------------- 132 133 134DISCUSSION 135---------- 136 137On Re-tagging 138~~~~~~~~~~~~~ 139 140What should you do when you tag a wrong commit and you would 141want to re-tag? 142 143If you never pushed anything out, just re-tag it. Use "-f" to 144replace the old one. And you're done. 145 146But if you have pushed things out (or others could just read 147your repository directly), then others will have already seen 148the old tag. In that case you can do one of two things: 149 150. The sane thing. 151Just admit you screwed up, and use a different name. Others have 152already seen one tag-name, and if you keep the same name, you 153may be in the situation that two people both have "version X", 154but they actually have 'different' "X"'s. So just call it "X.1" 155and be done with it. 156 157. The insane thing. 158You really want to call the new version "X" too, 'even though' 159others have already seen the old one. So just use 'git tag -f' 160again, as if you hadn't already published the old one. 161 162However, Git does *not* (and it should not) change tags behind 163users 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 165one. 166 167If somebody got a release tag from you, you cannot just change 168the tag for them by updating your own one. This is a big 169security issue, in that people MUST be able to trust their 170tag-names. If you really want to do the insane thing, you need 171to just fess up to it, and tell people that you messed up. You 172can do that by making a very public announcement saying: 173 174------------ 175Ok, I messed up, and I pushed out an earlier version tagged as X. I 176then fixed something, and retagged the *fixed* tree as X again. 177 178If you got the wrong tag, and want the new one, please delete 179the old one and fetch the new one by doing: 180 181 git tag -d X 182 git fetch origin tag X 183 184to get my updated tag. 185 186You can test which tag you have by doing 187 188 git rev-parse X 189 190which should return 0123456789abcdef.. if you have the new version. 191 192Sorry for the inconvenience. 193------------ 194 195Does this seem a bit complicated? It *should* be. There is no 196way that it would be correct to just "fix" it automatically. 197People need to know that their tags might have been changed. 198 199 200On Automatic following 201~~~~~~~~~~~~~~~~~~~~~~ 202 203If you are following somebody else's tree, you are most likely 204using remote-tracking branches (`refs/heads/origin` in traditional 205layout, or `refs/remotes/origin/master` in the separate-remote 206layout). You usually want the tags from the other end. 207 208On the other hand, if you are fetching because you would want a 209one-shot merge from somebody else, you typically do not want to 210get tags from there. This happens more often for people near 211the toplevel but not limited to them. Mere mortals when pulling 212from each other do not necessarily want to automatically get 213private anchor point tags from the other person. 214 215Often, "please pull" messages on the mailing list just provide 216two pieces of information: a repo URL and a branch name; this 217is designed to be easily cut&pasted at the end of a 'git fetch' 218command line: 219 220------------ 221Linus, please pull from 222 223 git://git..../proj.git master 224 225to get the following updates... 226------------ 227 228becomes: 229 230------------ 231$ git pull git://git..../proj.git master 232------------ 233 234In such a case, you do not want to automatically follow the other 235person's tags. 236 237One important aspect of git is its distributed nature, which 238largely means there is no inherent "upstream" or 239"downstream" in the system. On the face of it, the above 240example might seem to indicate that the tag namespace is owned 241by the upper echelon of people and that tags only flow downwards, but 242that is not the case. It only shows that the usage pattern 243determines who are interested in whose tags. 244 245A one-shot pull is a sign that a commit history is now crossing 246the boundary between one circle of people (e.g. "people who are 247primarily interested in the networking part of the kernel") who may 248have their own set of tags (e.g. "this is the third release 249candidate from the networking group to be proposed for general 250consumption with 2.6.21 release") to another circle of people 251(e.g. "people who integrate various subsystem improvements"). 252The latter are usually not interested in the detailed tags used 253internally in the former group (that is what "internal" means). 254That is why it is desirable not to follow tags automatically in 255this case. 256 257It may well be that among networking people, they may want to 258exchange the tags internal to their group, but in that workflow 259they are most likely tracking each other's progress by 260having remote-tracking branches. Again, the heuristic to automatically 261follow such tags is a good thing. 262 263 264On Backdating Tags 265~~~~~~~~~~~~~~~~~~ 266 267If you have imported some changes from another VCS and would like 268to add tags for major releases of your work, it is useful to be able 269to specify the date to embed inside of the tag object; such data in 270the tag object affects, for example, the ordering of tags in the 271gitweb interface. 272 273To set the date used in future tag objects, set the environment 274variable GIT_COMMITTER_DATE (see the later discussion of possible 275values; the most common form is "YYYY-MM-DD HH:MM"). 276 277For example: 278 279------------ 280$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1 281------------ 282 283include::date-formats.txt[] 284 285SEE ALSO 286-------- 287linkgit:git-check-ref-format[1]. 288 289GIT 290--- 291Part of the linkgit:git[1] suite