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