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