1GIT-TAG(1) Git Manual GIT-TAG(1)
2
6 git-tag - Create, list, delete or verify a tag object signed with GPG
7
9 git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]
10 <tagname> [<commit> | <object>]
11 git tag -d <tagname>...
12 git tag [-n[<num>]] -l [--contains <commit>] [<pattern>]
13 git tag -v <tagname>...
14
17 Add a tag reference in .git/refs/tags/, unless -d/-l/-v is given to
18 delete, list or verify tags.
19 Unless -f is given, the tag to be created must not yet exist in the
21 .git/refs/tags/ directory.
22 If one of -a, -s, or -u <key-id> is passed, the command creates a tag
24 object, and requires a tag message. Unless -m <msg> or -F <file> is
25 given, an editor is started for the user to type in the tag message.
26 If -m <msg> or -F <file> is given and -a, -s, and -u <key-id> are
28 absent, -a is implied.
29 Otherwise just a tag reference for the SHA1 object name of the commit
31 object is created (i.e. a lightweight tag).
32 A GnuPG signed tag object will be created when -s or -u <key-id> is
34 used. When -u <key-id> is not used, the committer identity for the
35 current user is used to find the GnuPG key for signing.
36
38 -a
39 Make an unsigned, annotated tag object
40 -s
42 Make a GPG-signed tag, using the default e-mail address’s key
43 -u <key-id>
45 Make a GPG-signed tag, using the given key
46 -f, --force
48 Replace an existing tag with the given name (instead of failing)
49 -d
51 Delete existing tags with the given names.
52 -v
54 Verify the gpg signature of the given tag names.
55 -n<num>
57 <num> specifies how many lines from the annotation, if any, are
58 printed when using -l. The default is not to print any annotation
59 lines. If no number is given to -n, only the first line is printed.
60 If the tag is not annotated, the commit message is displayed
61 instead.
62 -l <pattern>
64 List tags with names that match the given pattern (or all if no
65 pattern is given). Typing "git tag" without arguments, also lists
66 all tags.
67 --contains <commit>
69 Only list tags which contain the specified commit.
70 -m <msg>
72 Use the given tag message (instead of prompting). If multiple -m
73 options are given, their values are concatenated as separate
74 paragraphs. Implies -a if none of -a, -s, or -u <key-id> is given.
75 -F <file>
77 Take the tag message from the given file. Use - to read the message
78 from the standard input. Implies -a if none of -a, -s, or -u
79 <key-id> is given.
80 <tagname>
82 The name of the tag to create, delete, or describe. The new tag
83 name must pass all checks defined by git-check-ref-format(1). Some
84 of these checks may restrict the characters allowed in a tag name.
85
87 By default, git tag in sign-with-default mode (-s) will use your
88 committer identity (of the form "Your Name <your@email.address[1]>") to
89 find a key. If you want to use a different default key, you can specify
90 it in the repository configuration as follows:
91 [user]
93 signingkey = <gpg-key-id>
94
97 On Re-tagging
98 What should you do when you tag a wrong commit and you would want to
99 re-tag?
100 If you never pushed anything out, just re-tag it. Use "-f" to replace
102 the old one. And you’re done.
103 But if you have pushed things out (or others could just read your
105 repository directly), then others will have already seen the old tag.
106 In that case you can do one of two things:
107 1. The sane thing. Just admit you screwed up, and use a different
109 name. Others have already seen one tag-name, and if you keep the
110 same name, you may be in the situation that two people both have
111 "version X", but they actually have different "X"'s. So just call
112 it "X.1" and be done with it.
113 2. The insane thing. You really want to call the new version "X" too,
115 even though others have already seen the old one. So just use git
116 tag -f again, as if you hadn’t already published the old one.
117 However, Git does not (and it should not) change tags behind users
119 back. So if somebody already got the old tag, doing a git pull on your
120 tree shouldn’t just make them overwrite the old one.
121 If somebody got a release tag from you, you cannot just change the tag
123 for them by updating your own one. This is a big security issue, in
124 that people MUST be able to trust their tag-names. If you really want
125 to do the insane thing, you need to just fess up to it, and tell people
126 that you messed up. You can do that by making a very public
127 announcement saying:
128 Ok, I messed up, and I pushed out an earlier version tagged as X. I
130 then fixed something, and retagged the *fixed* tree as X again.
131 If you got the wrong tag, and want the new one, please delete
133 the old one and fetch the new one by doing:
134 git tag -d X
136 git fetch origin tag X
137 to get my updated tag.
139 You can test which tag you have by doing
141 git rev-parse X
143 which should return 0123456789abcdef.. if you have the new version.
145 Sorry for the inconvenience.
147 Does this seem a bit complicated? It should be. There is no way that it
150 would be correct to just "fix" it automatically. People need to know
151 that their tags might have been changed.
152 On Automatic following
154 If you are following somebody else’s tree, you are most likely using
155 remote-tracking branches (refs/heads/origin in traditional layout, or
156 refs/remotes/origin/master in the separate-remote layout). You usually
157 want the tags from the other end.
158 On the other hand, if you are fetching because you would want a
160 one-shot merge from somebody else, you typically do not want to get
161 tags from there. This happens more often for people near the toplevel
162 but not limited to them. Mere mortals when pulling from each other do
163 not necessarily want to automatically get private anchor point tags
164 from the other person.
165 Often, "please pull" messages on the mailing list just provide two
167 pieces of information: a repo URL and a branch name; this is designed
168 to be easily cut&pasted at the end of a git fetch command line:
169 Linus, please pull from
171 git://git..../proj.git master
173 to get the following updates...
175 becomes:
178 $ git pull git://git..../proj.git master
180 In such a case, you do not want to automatically follow the other
183 person’s tags.
184 One important aspect of git is its distributed nature, which largely
186 means there is no inherent "upstream" or "downstream" in the system. On
187 the face of it, the above example might seem to indicate that the tag
188 namespace is owned by the upper echelon of people and that tags only
189 flow downwards, but that is not the case. It only shows that the usage
190 pattern determines who are interested in whose tags.
191 A one-shot pull is a sign that a commit history is now crossing the
193 boundary between one circle of people (e.g. "people who are primarily
194 interested in the networking part of the kernel") who may have their
195 own set of tags (e.g. "this is the third release candidate from the
196 networking group to be proposed for general consumption with 2.6.21
197 release") to another circle of people (e.g. "people who integrate
198 various subsystem improvements"). The latter are usually not interested
199 in the detailed tags used internally in the former group (that is what
200 "internal" means). That is why it is desirable not to follow tags
201 automatically in this case.
202 It may well be that among networking people, they may want to exchange
204 the tags internal to their group, but in that workflow they are most
205 likely tracking each other’s progress by having remote-tracking
206 branches. Again, the heuristic to automatically follow such tags is a
207 good thing.
208 On Backdating Tags
210 If you have imported some changes from another VCS and would like to
211 add tags for major releases of your work, it is useful to be able to
212 specify the date to embed inside of the tag object; such data in the
213 tag object affects, for example, the ordering of tags in the gitweb
214 interface.
215 To set the date used in future tag objects, set the environment
217 variable GIT_COMMITTER_DATE (see the later discussion of possible
218 values; the most common form is "YYYY-MM-DD HH:MM").
219 For example:
221 $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
223
226 The GIT_AUTHOR_DATE, GIT_COMMITTER_DATE environment variables support
227 the following date formats:
228 Git internal format
230 It is <unix timestamp> <timezone offset>, where <unix timestamp> is
231 the number of seconds since the UNIX epoch. <timezone offset> is a
232 positive or negative offset from UTC. For example CET (which is 2
233 hours ahead UTC) is +0200.
234 RFC 2822
236 The standard email format as described by RFC 2822, for example
237 Thu, 07 Apr 2005 22:13:13 +0200.
238 ISO 8601
240 Time and date specified by the ISO 8601 standard, for example
241 2005-04-07T22:13:13. The parser accepts a space instead of the T
242 character as well.
243 Note
245 In addition, the date part is accepted in the following
246 formats: YYYY.MM.DD, MM/DD/YYYY and DD.MM.YYYY.
247
249 git-check-ref-format(1).
250
252 Written by Linus Torvalds <torvalds@osdl.org[2]>, Junio C Hamano
253 <gitster@pobox.com[3]> and Chris Wright <chrisw@osdl.org[4]>.
254
256 Documentation by David Greaves, Junio C Hamano and the git-list
257 <git@vger.kernel.org[5]>.
258
260 Part of the git(1) suite
261
263 1. your@email.address
264 mailto:your@email.address
265 2. torvalds@osdl.org
267 mailto:torvalds@osdl.org
268 3. gitster@pobox.com
270 mailto:gitster@pobox.com
271 4. chrisw@osdl.org
273 mailto:chrisw@osdl.org
274 5. git@vger.kernel.org
276 mailto:git@vger.kernel.org
277Git 1.7.4.4 04/11/2011 GIT-TAG(1)