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 | -v] [-m <msg> | -F <file>] <name> [<head>] 13'git-tag' -d <name>... 14'git-tag' -l [<pattern>] 15 16DESCRIPTION 17----------- 18Adds a 'tag' reference in `.git/refs/tags/` 19 20Unless `-f` is given, the tag must not yet exist in 21`.git/refs/tags/` directory. 22 23If one of `-a`, `-s`, or `-u <key-id>` is passed, the command 24creates a 'tag' object, and requires the tag message. Unless 25`-m <msg>` is given, an editor is started for the user to type 26in the tag message. 27 28Otherwise just the SHA1 object name of the commit object is 29written (i.e. a lightweight tag). 30 31A GnuPG signed tag object will be created when `-s` or `-u 32<key-id>` is used. When `-u <key-id>` is not used, the 33committer identity for the current user is used to find the 34GnuPG key for signing. 35 36`-d <tag>` deletes the tag. 37 38`-v <tag>` verifies the gpg signature of the tag. 39 40`-l <pattern>` lists tags that match the given pattern (or all 41if no pattern is given). 42 43OPTIONS 44------- 45-a:: 46 Make an unsigned, annotated tag object 47 48-s:: 49 Make a GPG-signed tag, using the default e-mail address's key 50 51-u <key-id>:: 52 Make a GPG-signed tag, using the given key 53 54-f:: 55 Replace an existing tag with the given name (instead of failing) 56 57-d:: 58 Delete existing tags with the given names. 59 60-v:: 61 Verify the gpg signature of given the tag 62 63-l <pattern>:: 64 List tags that match the given pattern (or all if no pattern is given). 65 66-m <msg>:: 67 Use the given tag message (instead of prompting) 68 69-F <file>:: 70 Take the tag message from the given file. Use '-' to 71 read the message from the standard input. 72 73CONFIGURATION 74------------- 75By default, git-tag in sign-with-default mode (-s) will use your 76committer identity (of the form "Your Name <your@email.address>") to 77find a key. If you want to use a different default key, you can specify 78it in the repository configuration as follows: 79 80[user] 81 signingkey = <gpg-key-id> 82 83 84DISCUSSION 85---------- 86 87On Re-tagging 88~~~~~~~~~~~~~ 89 90What should you do when you tag a wrong commit and you would 91want to re-tag? 92 93If you never pushed anything out, just re-tag it. Use "-f" to 94replace the old one. And you're done. 95 96But if you have pushed things out (or others could just read 97your repository directly), then others will have already seen 98the old tag. In that case you can do one of two things: 99 100. The sane thing. 101Just admit you screwed up, and use a different name. Others have 102already seen one tag-name, and if you keep the same name, you 103may be in the situation that two people both have "version X", 104but they actually have 'different' "X"'s. So just call it "X.1" 105and be done with it. 106 107. The insane thing. 108You really want to call the new version "X" too, 'even though' 109others have already seen the old one. So just use "git tag -f" 110again, as if you hadn't already published the old one. 111 112However, Git does *not* (and it should not)change tags behind 113users back. So if somebody already got the old tag, doing a "git 114pull" on your tree shouldn't just make them overwrite the old 115one. 116 117If somebody got a release tag from you, you cannot just change 118the tag for them by updating your own one. This is a big 119security issue, in that people MUST be able to trust their 120tag-names. If you really want to do the insane thing, you need 121to just fess up to it, and tell people that you messed up. You 122can do that by making a very public announcement saying: 123 124------------ 125Ok, I messed up, and I pushed out an earlier version tagged as X. I 126then fixed something, and retagged the *fixed* tree as X again. 127 128If you got the wrong tag, and want the new one, please delete 129the old one and fetch the new one by doing: 130 131 git tag -d X 132 git fetch origin tag X 133 134to get my updated tag. 135 136You can test which tag you have by doing 137 138 git rev-parse X 139 140which should return 0123456789abcdef.. if you have the new version. 141 142Sorry for inconvenience. 143------------ 144 145Does this seem a bit complicated? It *should* be. There is no 146way that it would be correct to just "fix" it behind peoples 147backs. People need to know that their tags might have been 148changed. 149 150 151On Automatic following 152~~~~~~~~~~~~~~~~~~~~~~ 153 154If you are following somebody else's tree, you are most likely 155using tracking branches (`refs/heads/origin` in traditional 156layout, or `refs/remotes/origin/master` in the separate-remote 157layout). You usually want the tags from the other end. 158 159On the other hand, if you are fetching because you would want a 160one-shot merge from somebody else, you typically do not want to 161get tags from there. This happens more often for people near 162the toplevel but not limited to them. Mere mortals when pulling 163from each other do not necessarily want to automatically get 164private anchor point tags from the other person. 165 166You would notice "please pull" messages on the mailing list says 167repo URL and branch name alone. This is designed to be easily 168cut&pasted to "git fetch" command line: 169 170------------ 171Linus, please pull from 172 173 git://git..../proj.git master 174 175to get the following updates... 176------------ 177 178becomes: 179 180------------ 181$ git pull git://git..../proj.git master 182------------ 183 184In such a case, you do not want to automatically follow other's 185tags. 186 187One important aspect of git is it is distributed, and being 188distributed largely means there is no inherent "upstream" or 189"downstream" in the system. On the face of it, the above 190example might seem to indicate that the tag namespace is owned 191by upper echelon of people and tags only flow downwards, but 192that is not the case. It only shows that the usage pattern 193determines who are interested in whose tags. 194 195A one-shot pull is a sign that a commit history is now crossing 196the boundary between one circle of people (e.g. "people who are 197primarily interested in networking part of the kernel") who may 198have their own set of tags (e.g. "this is the third release 199candidate from the networking group to be proposed for general 200consumption with 2.6.21 release") to another circle of people 201(e.g. "people who integrate various subsystem improvements"). 202The latter are usually not interested in the detailed tags used 203internally in the former group (that is what "internal" means). 204That is why it is desirable not to follow tags automatically in 205this case. 206 207It may well be that among networking people, they may want to 208exchange the tags internal to their group, but in that workflow 209they are most likely tracking with each other's progress by 210having tracking branches. Again, the heuristic to automatically 211follow such tags is a good thing. 212 213 214Author 215------ 216Written by Linus Torvalds <torvalds@osdl.org>, 217Junio C Hamano <junkio@cox.net> and Chris Wright <chrisw@osdl.org>. 218 219Documentation 220-------------- 221Documentation by David Greaves, Junio C Hamano and the git-list <git@vger.kernel.org>. 222 223GIT 224--- 225Part of the gitlink:git[7] suite