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