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