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