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