tag: clarify in the doc that a tag can refer to a non-commit object
[git/git.git] / Documentation / git-tag.txt
CommitLineData
215a7ad1
JH
1git-tag(1)
2==========
2cf565c5
DG
3
4NAME
5----
453c1e85 6git-tag - Create, list, delete or verify a tag object signed with GPG
2cf565c5
DG
7
8
2cf565c5
DG
9SYNOPSIS
10--------
b867c7c2 11[verse]
9eed6e40 12'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>] [-e]
b85e6c5f
NS
13 <tagname> [<commit> | <object>]
14'git tag' -d <tagname>...
80f4cd80 15'git tag' [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
783b8292
ÆAB
16 [--points-at <object>] [--column[=<options>] | --no-column]
17 [--create-reflog] [--sort=<key>] [--format=<format>]
18 [--[no-]merged [<commit>]] [<pattern>...]
07d347cf 19'git tag' -v [--format=<format>] <tagname>...
2cf565c5
DG
20
21DESCRIPTION
22-----------
18b07930 23
831e61f8 24Add a tag reference in `refs/tags/`, unless `-d/-l/-v` is given
cfb5e6b2 25to delete, list or verify tags.
b7e438f9 26
831e61f8 27Unless `-f` is given, the named tag must not yet exist.
b7e438f9 28
340f2c5e 29If one of `-a`, `-s`, or `-u <keyid>` is passed, the command
cfb5e6b2 30creates a 'tag' object, and requires a tag message. Unless
62e09ce9 31`-m <msg>` or `-F <file>` is given, an editor is started for the user to type
bc162e40 32in the tag message.
b7e438f9 33
340f2c5e 34If `-m <msg>` or `-F <file>` is given and `-a`, `-s`, and `-u <keyid>`
995e8df4
DS
35are absent, `-a` is implied.
36
590551ca
RD
37Otherwise, a tag reference that points directly at the given object
38(i.e., a lightweight tag) is created.
bc162e40
LT
39
40A GnuPG signed tag object will be created when `-s` or `-u
340f2c5e 41<keyid>` is used. When `-u <keyid>` is not used, the
bc162e40 42committer identity for the current user is used to find the
0c5e70f0
JH
43GnuPG key for signing. The configuration variable `gpg.program`
44is used to specify custom GnuPG binary.
45
eeff891a 46Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated"
29d55538
DS
47tags; they contain a creation date, the tagger name and e-mail, a
48tagging message, and an optional GnuPG signature. Whereas a
49"lightweight" tag is simply a name for an object (usually a commit
50object).
51
52Annotated tags are meant for release while lightweight tags are meant
53for private or temporary object labels. For this reason, some git
54commands for naming objects (like `git describe`) will ignore
55lightweight tags by default.
56
2cf565c5 57
d839091d
NW
58OPTIONS
59-------
60-a::
c97eff5a 61--annotate::
d839091d
NW
62 Make an unsigned, annotated tag object
63
64-s::
c97eff5a 65--sign::
0c5e70f0 66 Make a GPG-signed tag, using the default e-mail address's key.
d839091d 67
340f2c5e
MM
68-u <keyid>::
69--local-user=<keyid>::
0c5e70f0 70 Make a GPG-signed tag, using the given key.
d839091d
NW
71
72-f::
f7aec129 73--force::
d839091d
NW
74 Replace an existing tag with the given name (instead of failing)
75
76-d::
c97eff5a 77--delete::
453c1e85 78 Delete existing tags with the given names.
d839091d 79
0bc72abd 80-v::
c97eff5a 81--verify::
bc913167 82 Verify the GPG signature of the given tag names.
0bc72abd 83
3f36cbba 84-n<num>::
980ea5c5 85 <num> specifies how many lines from the annotation, if any,
6a338149
ÆAB
86 are printed when using -l. Implies `--list`.
87+
88The default is not to print any annotation lines.
89If no number is given to `-n`, only the first line is printed.
90If the tag is not annotated, the commit message is displayed instead.
980ea5c5 91
c485b24c
ÆAB
92-l::
93--list::
94 List tags. With optional `<pattern>...`, e.g. `git tag --list
95 'v-*'`, list only the tags that match the pattern(s).
96+
97Running "git tag" without arguments also lists all tags. The pattern
98is a shell wildcard (i.e., matched using fnmatch(3)). Multiple
99patterns may be given; if any of them matches, the tag is shown.
6a338149
ÆAB
100+
101This option is implicitly supplied if any other list-like option such
102as `--contains` is provided. See the documentation for each of those
103options for details.
b867c7c2 104
b7cc53e9
KN
105--sort=<key>::
106 Sort based on the key given. Prefix `-` to sort in
107 descending order of the value. You may use the --sort=<key> option
108 multiple times, in which case the last key becomes the primary
109 key. Also supports "version:refname" or "v:refname" (tag
64f7a264 110 names are treated as versions). The "version:refname" sort
c026557a
SG
111 order can also be affected by the "versionsort.suffix"
112 configuration variable.
b7cc53e9 113 The keys supported are the same as those in `git for-each-ref`.
ae9f6311 114 Sort order defaults to the value configured for the `tag.sort`
64f7a264
MH
115 variable if it exists, or lexicographic order otherwise. See
116 linkgit:git-config[1].
9ef176b5 117
0c88bf50
JK
118--color[=<when>]:
119 Respect any colors specified in the `--format` option. The
120 `<when>` field must be one of `always`, `never`, or `auto` (if
121 `<when>` is absent, behave as if `always` was given).
122
3bb16a8b
NTND
123-i::
124--ignore-case::
125 Sorting and filtering tags are case insensitive.
126
d96e3c15
NTND
127--column[=<options>]::
128--no-column::
129 Display tag listing in columns. See configuration variable
130 column.tag for option syntax.`--column` and `--no-column`
131 without options are equivalent to 'always' and 'never' respectively.
132+
133This option is only applicable when listing tags without annotation lines.
134
81966ab2
NTND
135--contains [<commit>]::
136 Only list tags which contain the specified commit (HEAD if not
6a338149 137 specified). Implies `--list`.
32c35cfb 138
ac3f5a34
ÆAB
139--no-contains [<commit>]::
140 Only list tags which don't contain the specified commit (HEAD if
141 not specified). Implies `--list`.
142
b0840609 143--merged [<commit>]::
8881d35c 144 Only list tags whose commits are reachable from the specified
17d6c744 145 commit (`HEAD` if not specified), incompatible with `--no-merged`.
b0840609
ÆAB
146
147--no-merged [<commit>]::
8881d35c 148 Only list tags whose commits are not reachable from the specified
17d6c744 149 commit (`HEAD` if not specified), incompatible with `--merged`.
0488792d 150
ae7706b9 151--points-at <object>::
1e0c3b68
ÆAB
152 Only list tags of the given object (HEAD if not
153 specified). Implies `--list`.
ae7706b9 154
d839091d 155-m <msg>::
c97eff5a 156--message=<msg>::
bd46c9a9 157 Use the given tag message (instead of prompting).
d99bf51a 158 If multiple `-m` options are given, their values are
bd46c9a9 159 concatenated as separate paragraphs.
340f2c5e 160 Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
995e8df4 161 is given.
d839091d 162
f79c73ce 163-F <file>::
c97eff5a 164--file=<file>::
f79c73ce
JS
165 Take the tag message from the given file. Use '-' to
166 read the message from the standard input.
340f2c5e 167 Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
995e8df4 168 is given.
2cf565c5 169
9eed6e40
NMC
170-e::
171--edit::
172 The message taken from file with `-F` and command line with
173 `-m` are usually used as the tag message unmodified.
174 This option lets you further edit the message taken from these sources.
175
d3e05983
KS
176--cleanup=<mode>::
177 This option sets how the tag message is cleaned up.
178 The '<mode>' can be one of 'verbatim', 'whitespace' and 'strip'. The
179 'strip' mode is default. The 'verbatim' mode does not change message at
180 all, 'whitespace' removes just leading/trailing whitespace lines and
181 'strip' removes both whitespace and commentary.
182
144c76fa 183--create-reflog::
341fb286
CW
184 Create a reflog for the tag. To globally enable reflogs for tags, see
185 `core.logAllRefUpdates` in linkgit:git-config[1].
67c70bd9
CW
186 The negated form `--no-create-reflog` only overrides an earlier
187 `--create-reflog`, but currently does not negate the setting of
c3342b36 188 `core.logAllRefUpdates`.
144c76fa 189
b85e6c5f
NS
190<tagname>::
191 The name of the tag to create, delete, or describe.
192 The new tag name must pass all checks defined by
193 linkgit:git-check-ref-format[1]. Some of these checks
194 may restrict the characters allowed in a tag name.
195
dd686cd4
TR
196<commit>::
197<object>::
198 The object that the new tag will refer to, usually a commit.
199 Defaults to HEAD.
200
df094741 201<format>::
e4933cee
MG
202 A string that interpolates `%(fieldname)` from a tag ref being shown
203 and the object it points at. The format is the same as
df094741 204 that of linkgit:git-for-each-ref[1]. When unspecified,
0571979b 205 defaults to `%(refname:strip=2)`.
dd686cd4 206
d67778ec
AP
207CONFIGURATION
208-------------
0b444cdb 209By default, 'git tag' in sign-with-default mode (-s) will use your
d595bdc1 210committer identity (of the form `Your Name <your@email.address>`) to
d67778ec
AP
211find a key. If you want to use a different default key, you can specify
212it in the repository configuration as follows:
213
86b9e017 214-------------------------------------
d67778ec 215[user]
340f2c5e 216 signingKey = <gpg-keyid>
86b9e017 217-------------------------------------
d67778ec 218
de121ffe 219`pager.tag` is only respected when listing tags, i.e., when `-l` is
ff1e7248 220used or implied. The default is to use a pager.
de121ffe 221See linkgit:git-config[1].
4853534e
JH
222
223DISCUSSION
224----------
225
226On Re-tagging
227~~~~~~~~~~~~~
228
229What should you do when you tag a wrong commit and you would
230want to re-tag?
231
232If you never pushed anything out, just re-tag it. Use "-f" to
233replace the old one. And you're done.
234
235But if you have pushed things out (or others could just read
236your repository directly), then others will have already seen
237the old tag. In that case you can do one of two things:
238
239. The sane thing.
240Just admit you screwed up, and use a different name. Others have
241already seen one tag-name, and if you keep the same name, you
242may be in the situation that two people both have "version X",
243but they actually have 'different' "X"'s. So just call it "X.1"
244and be done with it.
245
246. The insane thing.
247You really want to call the new version "X" too, 'even though'
0b444cdb 248others have already seen the old one. So just use 'git tag -f'
4853534e
JH
249again, as if you hadn't already published the old one.
250
06ada152 251However, Git does *not* (and it should not) change tags behind
46e56e81 252users back. So if somebody already got the old tag, doing a
0b444cdb 253'git pull' on your tree shouldn't just make them overwrite the old
4853534e
JH
254one.
255
256If somebody got a release tag from you, you cannot just change
257the tag for them by updating your own one. This is a big
258security issue, in that people MUST be able to trust their
259tag-names. If you really want to do the insane thing, you need
260to just fess up to it, and tell people that you messed up. You
261can do that by making a very public announcement saying:
262
263------------
264Ok, I messed up, and I pushed out an earlier version tagged as X. I
265then fixed something, and retagged the *fixed* tree as X again.
266
267If you got the wrong tag, and want the new one, please delete
268the old one and fetch the new one by doing:
269
270 git tag -d X
271 git fetch origin tag X
272
273to get my updated tag.
274
275You can test which tag you have by doing
276
277 git rev-parse X
278
279which should return 0123456789abcdef.. if you have the new version.
280
f1723ee6 281Sorry for the inconvenience.
4853534e
JH
282------------
283
284Does this seem a bit complicated? It *should* be. There is no
f1723ee6
MW
285way that it would be correct to just "fix" it automatically.
286People need to know that their tags might have been changed.
4853534e
JH
287
288
289On Automatic following
290~~~~~~~~~~~~~~~~~~~~~~
291
292If you are following somebody else's tree, you are most likely
749a2279
YK
293using remote-tracking branches (eg. `refs/remotes/origin/master`).
294You usually want the tags from the other end.
4853534e
JH
295
296On the other hand, if you are fetching because you would want a
297one-shot merge from somebody else, you typically do not want to
298get tags from there. This happens more often for people near
299the toplevel but not limited to them. Mere mortals when pulling
300from each other do not necessarily want to automatically get
301private anchor point tags from the other person.
302
f1723ee6
MW
303Often, "please pull" messages on the mailing list just provide
304two pieces of information: a repo URL and a branch name; this
305is designed to be easily cut&pasted at the end of a 'git fetch'
306command line:
4853534e
JH
307
308------------
309Linus, please pull from
310
311 git://git..../proj.git master
312
313to get the following updates...
314------------
315
316becomes:
317
318------------
319$ git pull git://git..../proj.git master
320------------
321
f1723ee6
MW
322In such a case, you do not want to automatically follow the other
323person's tags.
4853534e 324
2de9b711 325One important aspect of Git is its distributed nature, which
f1723ee6 326largely means there is no inherent "upstream" or
4853534e
JH
327"downstream" in the system. On the face of it, the above
328example might seem to indicate that the tag namespace is owned
f1723ee6 329by the upper echelon of people and that tags only flow downwards, but
4853534e
JH
330that is not the case. It only shows that the usage pattern
331determines who are interested in whose tags.
332
333A one-shot pull is a sign that a commit history is now crossing
334the boundary between one circle of people (e.g. "people who are
d99bf51a 335primarily interested in the networking part of the kernel") who may
4853534e
JH
336have their own set of tags (e.g. "this is the third release
337candidate from the networking group to be proposed for general
338consumption with 2.6.21 release") to another circle of people
339(e.g. "people who integrate various subsystem improvements").
340The latter are usually not interested in the detailed tags used
341internally in the former group (that is what "internal" means).
342That is why it is desirable not to follow tags automatically in
343this case.
344
345It may well be that among networking people, they may want to
346exchange the tags internal to their group, but in that workflow
f1723ee6 347they are most likely tracking each other's progress by
8b3f3f84 348having remote-tracking branches. Again, the heuristic to automatically
4853534e
JH
349follow such tags is a good thing.
350
351
5040beff
MO
352On Backdating Tags
353~~~~~~~~~~~~~~~~~~
354
355If you have imported some changes from another VCS and would like
356to add tags for major releases of your work, it is useful to be able
f1723ee6 357to specify the date to embed inside of the tag object; such data in
5040beff
MO
358the tag object affects, for example, the ordering of tags in the
359gitweb interface.
360
361To set the date used in future tag objects, set the environment
f1723ee6
MW
362variable GIT_COMMITTER_DATE (see the later discussion of possible
363values; the most common form is "YYYY-MM-DD HH:MM").
5040beff 364
f1723ee6 365For example:
5040beff
MO
366
367------------
055b6615 368$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
5040beff
MO
369------------
370
f1723ee6 371include::date-formats.txt[]
5040beff 372
b85e6c5f
NS
373SEE ALSO
374--------
375linkgit:git-check-ref-format[1].
b150794d 376linkgit:git-config[1].
b85e6c5f 377
2cf565c5
DG
378GIT
379---
9e1f0a85 380Part of the linkgit:git[1] suite