freshlybakedca.ke
Git fork
1git-tag(1)
2==========
3
4NAME
5----
6git-tag - Create, list, delete or verify tags
7
8
9SYNOPSIS
10--------
11[synopsis]
12git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>] [-e]
13 [(--trailer <token>[(=|:)<value>])...]
14 <tagname> [<commit> | <object>]
15git tag -d <tagname>...
16git tag [-n[<num>]] -l [--contains <commit>] [--no-contains <commit>]
17 [--points-at <object>] [--column[=<options>] | --no-column]
18 [--create-reflog] [--sort=<key>] [--format=<format>]
19 [--merged <commit>] [--no-merged <commit>] [<pattern>...]
20git tag -v [--format=<format>] <tagname>...
21
22DESCRIPTION
23-----------
24
25Add a tag reference in `refs/tags/`, unless `-d`/`-l`/`-v` is given
26to delete, list or verify tags.
27
28Unless `-f` is given, the named tag must not yet exist.
29
30If one of `-a`, `-s`, or `-u <key-id>` is passed, the command
31creates a 'tag' object, and requires a tag message. Unless
32`-m <msg>` or `-F <file>` is given, an editor is started for the user to type
33in the tag message.
34
35If `-m <msg>` or `-F <file>` or `--trailer <token>[=<value>]` is given
36and `-a`, `-s`, and `-u <key-id>` are absent, `-a` is implied.
37
38Otherwise, a tag reference that points directly at the given object
39(i.e., a lightweight tag) is created.
40
41A cryptographically signed tag object will be created when `-s` or
42`-u <key-id>` is used. The signing backend (GPG, X.509, SSH, etc.) is
43controlled by the `gpg.format` configuration variable, defaulting to
44OpenPGP. When `-u <key-id>` is not used, the committer identity for
45the current user is used to find the key for signing. The
46configuration variable `gpg.program` is used to specify a custom
47signing binary.
48
49Tag objects (created with `-a`, `-s`, or `-u`) are called "annotated"
50tags; they contain a creation date, the tagger name and e-mail, a
51tagging message, and an optional cryptographic signature. Whereas a
52"lightweight" tag is simply a name for an object (usually a commit
53object).
54
55Annotated tags are meant for release while lightweight tags are meant
56for private or temporary object labels. For this reason, some git
57commands for naming objects (like `git describe`) will ignore
58lightweight tags by default.
59
60
61OPTIONS
62-------
63`-a`::
64`--annotate`::
65 Make an unsigned, annotated tag object
66
67`-s`::
68`--sign`::
69 Make a cryptographically signed tag, using the default signing
70 key. The signing backend used depends on the `gpg.format`
71 configuration variable. The default key is determined by the
72 backend. For GPG, it's based on the committer's email address,
73 while for SSH it may be a specific key file or agent
74 identity. See linkgit:git-config[1].
75
76`--no-sign`::
77 Override `tag.gpgSign` configuration variable that is
78 set to force each and every tag to be signed.
79
80`-u <key-id>`::
81`--local-user=<key-id>`::
82 Make a cryptographically signed tag using the given key. The
83 format of the <key-id> and the backend used depend on the
84 `gpg.format` configuration variable. See
85 linkgit:git-config[1].
86
87`-f`::
88`--force`::
89 Replace an existing tag with the given name (instead of failing)
90
91`-d`::
92`--delete`::
93 Delete existing tags with the given names.
94
95`-v`::
96`--verify`::
97 Verify the cryptographic signature of the given tags.
98
99`-n<num>`::
100 _<num>_ specifies how many lines from the annotation, if any,
101 are printed when using `-l`. Implies `--list`.
102+
103The default is not to print any annotation lines.
104If no number is given to `-n`, only the first line is printed.
105If the tag is not annotated, the commit message is displayed instead.
106
107`-l`::
108`--list`::
109 List tags. With optional `<pattern>...`, e.g. `git tag --list
110 'v-*'`, list only the tags that match the pattern(s).
111+
112Running `git tag` without arguments also lists all tags. The pattern
113is a shell wildcard (i.e., matched using `fnmatch`(3)). Multiple
114patterns may be given; if any of them matches, the tag is shown.
115+
116This option is implicitly supplied if any other list-like option such
117as `--contains` is provided. See the documentation for each of those
118options for details.
119
120`--sort=<key>`::
121 Sort based on the key given. Prefix `-` to sort in
122 descending order of the value. You may use the `--sort=<key>` option
123 multiple times, in which case the last _<key>_ becomes the primary
124 key. Also supports "`version:refname`" or "`v:refname`" (tag
125 names are treated as versions). The "`version:refname`" sort
126 order can also be affected by the "`versionsort.suffix`"
127 configuration variable.
128 The keys supported are the same as those in `git for-each-ref`.
129 Sort order defaults to the value configured for the `tag.sort`
130 variable if it exists, or lexicographic order otherwise. See
131 linkgit:git-config[1].
132
133`--color[=<when>]`::
134 Respect any colors specified in the `--format` option. The
135 _<when>_ field must be one of `always`, `never`, or `auto` (if
136 _<when>_ is absent, behave as if `always` was given).
137
138`-i`::
139`--ignore-case`::
140 Sorting and filtering tags are case insensitive.
141
142`--omit-empty`::
143 Do not print a newline after formatted refs where the format expands
144 to the empty string.
145
146`--column[=<options>]`::
147`--no-column`::
148 Display tag listing in columns. See configuration variable
149 `column.tag` for option syntax. `--column` and `--no-column`
150 without options are equivalent to `always` and `never` respectively.
151+
152This option is only applicable when listing tags without annotation lines.
153
154`--contains [<commit>]`::
155 Only list tags which contain _<commit>_ (`HEAD` if not
156 specified). Implies `--list`.
157
158`--no-contains [<commit>]`::
159 Only list tags which don't contain _<commit>_ (`HEAD` if
160 not specified). Implies `--list`.
161
162`--merged [<commit>]`::
163 Only list tags whose commits are reachable from
164 _<commit>_ (`HEAD` if not specified).
165
166`--no-merged [<commit>]`::
167 Only list tags whose commits are not reachable from
168 _<commit>_ (`HEAD` if not specified).
169
170`--points-at [<object>]`::
171 Only list tags of _<object>_ (`HEAD` if not
172 specified). Implies `--list`.
173
174`-m <msg>`::
175`--message=<msg>`::
176 Use _<msg>_ (instead of prompting).
177 If multiple `-m` options are given, their values are
178 concatenated as separate paragraphs.
179 Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
180 is given.
181
182`-F <file>`::
183`--file=<file>`::
184 Take the tag message from _<file>_. Use `-` to
185 read the message from the standard input.
186 Implies `-a` if none of `-a`, `-s`, or `-u <key-id>`
187 is given.
188
189`--trailer <token>[(=|:)<value>]`::
190 Specify a (_<token>_, _<value>_) pair that should be applied as a
191 trailer. (e.g. `git tag --trailer "Custom-Key: value"`
192 will add a "Custom-Key" trailer to the tag message.)
193 The `trailer.*` configuration variables
194 (linkgit:git-interpret-trailers[1]) can be used to define if
195 a duplicated trailer is omitted, where in the run of trailers
196 each trailer would appear, and other details.
197 The trailers can be extracted in `git tag --list`, using
198 `--format="%(trailers)"` placeholder.
199
200`-e`::
201`--edit`::
202 Let further edit the message taken from file with `-F` and command line with
203 `-m`.
204
205`--cleanup=<mode>`::
206 Set how the tag message is cleaned up.
207 The _<mode>_ can be one of `verbatim`, `whitespace` and `strip`. The
208 `strip` mode is default. The `verbatim` mode does not change message at
209 all, `whitespace` removes just leading/trailing whitespace lines and
210 `strip` removes both whitespace and commentary.
211
212`--create-reflog`::
213 Create a reflog for the tag. To globally enable reflogs for tags, see
214 `core.logAllRefUpdates` in linkgit:git-config[1].
215 The negated form `--no-create-reflog` only overrides an earlier
216 `--create-reflog`, but currently does not negate the setting of
217 `core.logAllRefUpdates`.
218
219`--format=<format>`::
220 A string that interpolates `%(fieldname)` from a tag ref being shown
221 and the object it points at. The format is the same as
222 that of linkgit:git-for-each-ref[1]. When unspecified,
223 defaults to `%(refname:strip=2)`.
224
225_<tagname>_::
226 The name of the tag to create, delete, or describe.
227 The new tag name must pass all checks defined by
228 linkgit:git-check-ref-format[1]. Some of these checks
229 may restrict the characters allowed in a tag name.
230
231_<commit>_::
232_<object>_::
233 The object that the new tag will refer to, usually a commit.
234 Defaults to `HEAD`.
235
236CONFIGURATION
237-------------
238By default, `git tag` in sign-with-default mode (`-s`) will use your
239committer identity (of the form `Your Name <your@email.address>`) to
240find a key. If you want to use a different default key, you can specify
241it in the repository configuration as follows:
242
243-------------------------------------
244[user]
245 signingKey = <key-id>
246-------------------------------------
247
248The signing backend can be chosen via the `gpg.format` configuration
249variable, which defaults to `openpgp`. See linkgit:git-config[1]
250for a list of other supported formats.
251
252The path to the program used for each signing backend can be specified
253with the `gpg.<format>.program` configuration variable. For the
254`openpgp` backend, `gpg.program` can be used as a synonym for
255`gpg.openpgp.program`. See linkgit:git-config[1] for details.
256
257`pager.tag` is only respected when listing tags, i.e., when `-l` is
258used or implied. The default is to use a pager.
259
260See linkgit:git-config[1] for more details and other configuration
261variables.
262
263DISCUSSION
264----------
265
266On Re-tagging
267~~~~~~~~~~~~~
268
269What should you do when you tag a wrong commit and you would
270want to re-tag?
271
272If you never pushed anything out, just re-tag it. Use `-f` to
273replace the old one. And you're done.
274
275But if you have pushed things out (or others could just read
276your repository directly), then others will have already seen
277the old tag. In that case you can do one of two things:
278
279. The sane thing.
280 Just admit you screwed up, and use a different name. Others have
281 already seen one tag-name, and if you keep the same name, you
282 may be in the situation that two people both have "version X",
283 but they actually have 'different' "X"'s. So just call it "X.1"
284 and be done with it.
285
286. The insane thing.
287 You really want to call the new version "X" too, 'even though'
288 others have already seen the old one. So just use `git tag -f`
289 again, as if you hadn't already published the old one.
290
291However, Git does *not* (and it should not) change tags behind
292users back. So if somebody already got the old tag, doing a
293`git pull` on your tree shouldn't just make them overwrite the old
294one.
295
296If somebody got a release tag from you, you cannot just change
297the tag for them by updating your own one. This is a big
298security issue, in that people MUST be able to trust their
299tag-names. If you really want to do the insane thing, you need
300to just fess up to it, and tell people that you messed up. You
301can do that by making a very public announcement saying:
302
303------------
304Ok, I messed up, and I pushed out an earlier version tagged as X. I
305then fixed something, and retagged the *fixed* tree as X again.
306
307If you got the wrong tag, and want the new one, please delete
308the old one and fetch the new one by doing:
309
310 git tag -d X
311 git fetch origin tag X
312
313to get my updated tag.
314
315You can test which tag you have by doing
316
317 git rev-parse X
318
319which should return 0123456789abcdef.. if you have the new version.
320
321Sorry for the inconvenience.
322------------
323
324Does this seem a bit complicated? It *should* be. There is no
325way that it would be correct to just "fix" it automatically.
326People need to know that their tags might have been changed.
327
328
329On Automatic following
330~~~~~~~~~~~~~~~~~~~~~~
331
332If you are following somebody else's tree, you are most likely
333using remote-tracking branches (eg. `refs/remotes/origin/master`).
334You usually want the tags from the other end.
335
336On the other hand, if you are fetching because you would want a
337one-shot merge from somebody else, you typically do not want to
338get tags from there. This happens more often for people near
339the toplevel but not limited to them. Mere mortals when pulling
340from each other do not necessarily want to automatically get
341private anchor point tags from the other person.
342
343Often, "please pull" messages on the mailing list just provide
344two pieces of information: a repo URL and a branch name; this
345is designed to be easily cut&pasted at the end of a `git fetch`
346command line:
347
348------------
349Linus, please pull from
350
351 git://git..../proj.git master
352
353to get the following updates...
354------------
355
356becomes:
357
358------------
359$ git pull git://git..../proj.git master
360------------
361
362In such a case, you do not want to automatically follow the other
363person's tags.
364
365One important aspect of Git is its distributed nature, which
366largely means there is no inherent "upstream" or
367"downstream" in the system. On the face of it, the above
368example might seem to indicate that the tag namespace is owned
369by the upper echelon of people and that tags only flow downwards, but
370that is not the case. It only shows that the usage pattern
371determines who are interested in whose tags.
372
373A one-shot pull is a sign that a commit history is now crossing
374the boundary between one circle of people (e.g. "people who are
375primarily interested in the networking part of the kernel") who may
376have their own set of tags (e.g. "this is the third release
377candidate from the networking group to be proposed for general
378consumption with 2.6.21 release") to another circle of people
379(e.g. "people who integrate various subsystem improvements").
380The latter are usually not interested in the detailed tags used
381internally in the former group (that is what "internal" means).
382That is why it is desirable not to follow tags automatically in
383this case.
384
385It may well be that among networking people, they may want to
386exchange the tags internal to their group, but in that workflow
387they are most likely tracking each other's progress by
388having remote-tracking branches. Again, the heuristic to automatically
389follow such tags is a good thing.
390
391
392On Backdating Tags
393~~~~~~~~~~~~~~~~~~
394
395If you have imported some changes from another VCS and would like
396to add tags for major releases of your work, it is useful to be able
397to specify the date to embed inside of the tag object; such data in
398the tag object affects, for example, the ordering of tags in the
399gitweb interface.
400
401To set the date used in future tag objects, set the environment
402variable GIT_COMMITTER_DATE (see the later discussion of possible
403values; the most common form is "YYYY-MM-DD HH:MM").
404
405For example:
406
407------------
408$ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
409------------
410
411include::date-formats.adoc[]
412
413FILES
414-----
415
416`$GIT_DIR/TAG_EDITMSG`::
417 This file contains the message of an in-progress annotated
418 tag. If `git tag` exits due to an error before creating an
419 annotated tag then the tag message that has been provided by the
420 user in an editor session will be available in this file, but
421 may be overwritten by the next invocation of `git tag`.
422
423CONFIGURATION
424-------------
425
426include::includes/cmd-config-section-all.adoc[]
427
428:git-tag: 1
429include::config/tag.adoc[]
430
431NOTES
432-----
433
434include::ref-reachability-filters.adoc[]
435
436SEE ALSO
437--------
438linkgit:git-check-ref-format[1].
439linkgit:git-config[1].
440
441GIT
442---
443Part of the linkgit:git[1] suite