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