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