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