tag: change default of `pager.tag` to "on"
[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]
340f2c5e 12'git tag' [-a | -s | -u <keyid>] [-f] [-m <msg> | -F <file>]
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
d5fa1f1a 37Otherwise just a tag reference for the SHA-1 object name of the commit object is
cfb5e6b2 38created (i.e. a lightweight tag).
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
3bb16a8b
NTND
118-i::
119--ignore-case::
120 Sorting and filtering tags are case insensitive.
121
d96e3c15
NTND
122--column[=<options>]::
123--no-column::
124 Display tag listing in columns. See configuration variable
125 column.tag for option syntax.`--column` and `--no-column`
126 without options are equivalent to 'always' and 'never' respectively.
127+
128This option is only applicable when listing tags without annotation lines.
129
81966ab2
NTND
130--contains [<commit>]::
131 Only list tags which contain the specified commit (HEAD if not
6a338149 132 specified). Implies `--list`.
32c35cfb 133
ac3f5a34
ÆAB
134--no-contains [<commit>]::
135 Only list tags which don't contain the specified commit (HEAD if
136 not specified). Implies `--list`.
137
b0840609 138--merged [<commit>]::
8881d35c 139 Only list tags whose commits are reachable from the specified
17d6c744 140 commit (`HEAD` if not specified), incompatible with `--no-merged`.
b0840609
ÆAB
141
142--no-merged [<commit>]::
8881d35c 143 Only list tags whose commits are not reachable from the specified
17d6c744 144 commit (`HEAD` if not specified), incompatible with `--merged`.
0488792d 145
ae7706b9 146--points-at <object>::
1e0c3b68
ÆAB
147 Only list tags of the given object (HEAD if not
148 specified). Implies `--list`.
ae7706b9 149
d839091d 150-m <msg>::
c97eff5a 151--message=<msg>::
bd46c9a9 152 Use the given tag message (instead of prompting).
d99bf51a 153 If multiple `-m` options are given, their values are
bd46c9a9 154 concatenated as separate paragraphs.
340f2c5e 155 Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
995e8df4 156 is given.
d839091d 157
f79c73ce 158-F <file>::
c97eff5a 159--file=<file>::
f79c73ce
JS
160 Take the tag message from the given file. Use '-' to
161 read the message from the standard input.
340f2c5e 162 Implies `-a` if none of `-a`, `-s`, or `-u <keyid>`
995e8df4 163 is given.
2cf565c5 164
d3e05983
KS
165--cleanup=<mode>::
166 This option sets how the tag message is cleaned up.
167 The '<mode>' can be one of 'verbatim', 'whitespace' and 'strip'. The
168 'strip' mode is default. The 'verbatim' mode does not change message at
169 all, 'whitespace' removes just leading/trailing whitespace lines and
170 'strip' removes both whitespace and commentary.
171
144c76fa 172--create-reflog::
341fb286
CW
173 Create a reflog for the tag. To globally enable reflogs for tags, see
174 `core.logAllRefUpdates` in linkgit:git-config[1].
67c70bd9
CW
175 The negated form `--no-create-reflog` only overrides an earlier
176 `--create-reflog`, but currently does not negate the setting of
177 `core.logallrefupdates`.
144c76fa 178
b85e6c5f
NS
179<tagname>::
180 The name of the tag to create, delete, or describe.
181 The new tag name must pass all checks defined by
182 linkgit:git-check-ref-format[1]. Some of these checks
183 may restrict the characters allowed in a tag name.
184
dd686cd4
TR
185<commit>::
186<object>::
187 The object that the new tag will refer to, usually a commit.
188 Defaults to HEAD.
189
df094741
KN
190<format>::
191 A string that interpolates `%(fieldname)` from the object
192 pointed at by a ref being shown. The format is the same as
193 that of linkgit:git-for-each-ref[1]. When unspecified,
0571979b 194 defaults to `%(refname:strip=2)`.
dd686cd4 195
d67778ec
AP
196CONFIGURATION
197-------------
0b444cdb 198By default, 'git tag' in sign-with-default mode (-s) will use your
d595bdc1 199committer identity (of the form `Your Name <your@email.address>`) to
d67778ec
AP
200find a key. If you want to use a different default key, you can specify
201it in the repository configuration as follows:
202
86b9e017 203-------------------------------------
d67778ec 204[user]
340f2c5e 205 signingKey = <gpg-keyid>
86b9e017 206-------------------------------------
d67778ec 207
de121ffe 208`pager.tag` is only respected when listing tags, i.e., when `-l` is
ff1e7248 209used or implied. The default is to use a pager.
de121ffe 210See linkgit:git-config[1].
4853534e
JH
211
212DISCUSSION
213----------
214
215On Re-tagging
216~~~~~~~~~~~~~
217
218What should you do when you tag a wrong commit and you would
219want to re-tag?
220
221If you never pushed anything out, just re-tag it. Use "-f" to
222replace the old one. And you're done.
223
224But if you have pushed things out (or others could just read
225your repository directly), then others will have already seen
226the old tag. In that case you can do one of two things:
227
228. The sane thing.
229Just admit you screwed up, and use a different name. Others have
230already seen one tag-name, and if you keep the same name, you
231may be in the situation that two people both have "version X",
232but they actually have 'different' "X"'s. So just call it "X.1"
233and be done with it.
234
235. The insane thing.
236You really want to call the new version "X" too, 'even though'
0b444cdb 237others have already seen the old one. So just use 'git tag -f'
4853534e
JH
238again, as if you hadn't already published the old one.
239
06ada152 240However, Git does *not* (and it should not) change tags behind
46e56e81 241users back. So if somebody already got the old tag, doing a
0b444cdb 242'git pull' on your tree shouldn't just make them overwrite the old
4853534e
JH
243one.
244
245If somebody got a release tag from you, you cannot just change
246the tag for them by updating your own one. This is a big
247security issue, in that people MUST be able to trust their
248tag-names. If you really want to do the insane thing, you need
249to just fess up to it, and tell people that you messed up. You
250can do that by making a very public announcement saying:
251
252------------
253Ok, I messed up, and I pushed out an earlier version tagged as X. I
254then fixed something, and retagged the *fixed* tree as X again.
255
256If you got the wrong tag, and want the new one, please delete
257the old one and fetch the new one by doing:
258
259 git tag -d X
260 git fetch origin tag X
261
262to get my updated tag.
263
264You can test which tag you have by doing
265
266 git rev-parse X
267
268which should return 0123456789abcdef.. if you have the new version.
269
f1723ee6 270Sorry for the inconvenience.
4853534e
JH
271------------
272
273Does this seem a bit complicated? It *should* be. There is no
f1723ee6
MW
274way that it would be correct to just "fix" it automatically.
275People need to know that their tags might have been changed.
4853534e
JH
276
277
278On Automatic following
279~~~~~~~~~~~~~~~~~~~~~~
280
281If you are following somebody else's tree, you are most likely
749a2279
YK
282using remote-tracking branches (eg. `refs/remotes/origin/master`).
283You usually want the tags from the other end.
4853534e
JH
284
285On the other hand, if you are fetching because you would want a
286one-shot merge from somebody else, you typically do not want to
287get tags from there. This happens more often for people near
288the toplevel but not limited to them. Mere mortals when pulling
289from each other do not necessarily want to automatically get
290private anchor point tags from the other person.
291
f1723ee6
MW
292Often, "please pull" messages on the mailing list just provide
293two pieces of information: a repo URL and a branch name; this
294is designed to be easily cut&pasted at the end of a 'git fetch'
295command line:
4853534e
JH
296
297------------
298Linus, please pull from
299
300 git://git..../proj.git master
301
302to get the following updates...
303------------
304
305becomes:
306
307------------
308$ git pull git://git..../proj.git master
309------------
310
f1723ee6
MW
311In such a case, you do not want to automatically follow the other
312person's tags.
4853534e 313
2de9b711 314One important aspect of Git is its distributed nature, which
f1723ee6 315largely means there is no inherent "upstream" or
4853534e
JH
316"downstream" in the system. On the face of it, the above
317example might seem to indicate that the tag namespace is owned
f1723ee6 318by the upper echelon of people and that tags only flow downwards, but
4853534e
JH
319that is not the case. It only shows that the usage pattern
320determines who are interested in whose tags.
321
322A one-shot pull is a sign that a commit history is now crossing
323the boundary between one circle of people (e.g. "people who are
d99bf51a 324primarily interested in the networking part of the kernel") who may
4853534e
JH
325have their own set of tags (e.g. "this is the third release
326candidate from the networking group to be proposed for general
327consumption with 2.6.21 release") to another circle of people
328(e.g. "people who integrate various subsystem improvements").
329The latter are usually not interested in the detailed tags used
330internally in the former group (that is what "internal" means).
331That is why it is desirable not to follow tags automatically in
332this case.
333
334It may well be that among networking people, they may want to
335exchange the tags internal to their group, but in that workflow
f1723ee6 336they are most likely tracking each other's progress by
8b3f3f84 337having remote-tracking branches. Again, the heuristic to automatically
4853534e
JH
338follow such tags is a good thing.
339
340
5040beff
MO
341On Backdating Tags
342~~~~~~~~~~~~~~~~~~
343
344If you have imported some changes from another VCS and would like
345to add tags for major releases of your work, it is useful to be able
f1723ee6 346to specify the date to embed inside of the tag object; such data in
5040beff
MO
347the tag object affects, for example, the ordering of tags in the
348gitweb interface.
349
350To set the date used in future tag objects, set the environment
f1723ee6
MW
351variable GIT_COMMITTER_DATE (see the later discussion of possible
352values; the most common form is "YYYY-MM-DD HH:MM").
5040beff 353
f1723ee6 354For example:
5040beff
MO
355
356------------
055b6615 357$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
5040beff
MO
358------------
359
f1723ee6 360include::date-formats.txt[]
5040beff 361
b85e6c5f
NS
362SEE ALSO
363--------
364linkgit:git-check-ref-format[1].
b150794d 365linkgit:git-config[1].
b85e6c5f 366
2cf565c5
DG
367GIT
368---
9e1f0a85 369Part of the linkgit:git[1] suite