1GIT-TAG(1) Git Manual GIT-TAG(1)
2
6 git-tag - Create, list, delete or verify a tag object signed with GPG
7
9 git tag [-a | -s | -u <key-id>] [-f] [-m <msg> | -F <file>]
10 <tagname> [<commit> | <object>]
11 git tag -d <tagname>...
12 git tag [-n[<num>]] -l [--contains <commit>] [--points-at <object>]
13 [--column[=<options>] | --no-column] [<pattern>...]
14 [<pattern>...]
15 git tag -v <tagname>...
16
19 Add a tag reference in refs/tags/, unless -d/-l/-v is given to delete,
20 list or verify tags.
21 Unless -f is given, the named tag must not yet exist.
23 If one of -a, -s, or -u <key-id> is passed, the command creates a tag
25 object, and requires a tag message. Unless -m <msg> or -F <file> is
26 given, an editor is started for the user to type in the tag message.
27 If -m <msg> or -F <file> is given and -a, -s, and -u <key-id> are
29 absent, -a is implied.
30 Otherwise just a tag reference for the SHA-1 object name of the commit
32 object is created (i.e. a lightweight tag).
33 A GnuPG signed tag object will be created when -s or -u <key-id> is
35 used. When -u <key-id> is not used, the committer identity for the
36 current user is used to find the GnuPG key for signing. The
37 configuration variable gpg.program is used to specify custom GnuPG
38 binary.
39
41 -a, --annotate
42 Make an unsigned, annotated tag object
43 -s, --sign
45 Make a GPG-signed tag, using the default e-mail address’s key.
46 -u <key-id>, --local-user=<key-id>
48 Make a GPG-signed tag, using the given key.
49 -f, --force
51 Replace an existing tag with the given name (instead of failing)
52 -d, --delete
54 Delete existing tags with the given names.
55 -v, --verify
57 Verify the gpg signature of the given tag names.
58 -n<num>
60 <num> specifies how many lines from the annotation, if any, are
61 printed when using -l. The default is not to print any annotation
62 lines. If no number is given to -n, only the first line is printed.
63 If the tag is not annotated, the commit message is displayed
64 instead.
65 -l <pattern>, --list <pattern>
67 List tags with names that match the given pattern (or all if no
68 pattern is given). Running "git tag" without arguments also lists
69 all tags. The pattern is a shell wildcard (i.e., matched using
70 fnmatch(3)). Multiple patterns may be given; if any of them
71 matches, the tag is shown.
72 --column[=<options>], --no-column
74 Display tag listing in columns. See configuration variable
75 column.tag for option syntax.--column and --no-column without
76 options are equivalent to always and never respectively.
77 This option is only applicable when listing tags without annotation
79 lines.
80 --contains <commit>
82 Only list tags which contain the specified commit.
83 --points-at <object>
85 Only list tags of the given object.
86 -m <msg>, --message=<msg>
88 Use the given tag message (instead of prompting). If multiple -m
89 options are given, their values are concatenated as separate
90 paragraphs. Implies -a if none of -a, -s, or -u <key-id> is given.
91 -F <file>, --file=<file>
93 Take the tag message from the given file. Use - to read the message
94 from the standard input. Implies -a if none of -a, -s, or -u
95 <key-id> is given.
96 --cleanup=<mode>
98 This option sets how the tag message is cleaned up. The <mode> can
99 be one of verbatim, whitespace and strip. The strip mode is
100 default. The verbatim mode does not change message at all,
101 whitespace removes just leading/trailing whitespace lines and strip
102 removes both whitespace and commentary.
103 <tagname>
105 The name of the tag to create, delete, or describe. The new tag
106 name must pass all checks defined by git-check-ref-format(1). Some
107 of these checks may restrict the characters allowed in a tag name.
108 <commit>, <object>
110 The object that the new tag will refer to, usually a commit.
111 Defaults to HEAD.
112
114 By default, git tag in sign-with-default mode (-s) will use your
115 committer identity (of the form "Your Name <your@email.address>") to
116 find a key. If you want to use a different default key, you can specify
117 it in the repository configuration as follows:
118 [user]
120 signingkey = <gpg-key-id>
121
124 On Re-tagging
125 What should you do when you tag a wrong commit and you would want to
126 re-tag?
127 If you never pushed anything out, just re-tag it. Use "-f" to replace
129 the old one. And you’re done.
130 But if you have pushed things out (or others could just read your
132 repository directly), then others will have already seen the old tag.
133 In that case you can do one of two things:
134 1. The sane thing. Just admit you screwed up, and use a different
136 name. Others have already seen one tag-name, and if you keep the
137 same name, you may be in the situation that two people both have
138 "version X", but they actually have different "X"'s. So just call
139 it "X.1" and be done with it.
140 2. The insane thing. You really want to call the new version "X" too,
142 even though others have already seen the old one. So just use git
143 tag -f again, as if you hadn’t already published the old one.
144 However, Git does not (and it should not) change tags behind users
146 back. So if somebody already got the old tag, doing a git pull on your
147 tree shouldn’t just make them overwrite the old one.
148 If somebody got a release tag from you, you cannot just change the tag
150 for them by updating your own one. This is a big security issue, in
151 that people MUST be able to trust their tag-names. If you really want
152 to do the insane thing, you need to just fess up to it, and tell people
153 that you messed up. You can do that by making a very public
154 announcement saying:
155 Ok, I messed up, and I pushed out an earlier version tagged as X. I
157 then fixed something, and retagged the *fixed* tree as X again.
158 If you got the wrong tag, and want the new one, please delete
160 the old one and fetch the new one by doing:
161 git tag -d X
163 git fetch origin tag X
164 to get my updated tag.
166 You can test which tag you have by doing
168 git rev-parse X
170 which should return 0123456789abcdef.. if you have the new version.
172 Sorry for the inconvenience.
174 Does this seem a bit complicated? It should be. There is no way that it
177 would be correct to just "fix" it automatically. People need to know
178 that their tags might have been changed.
179 On Automatic following
181 If you are following somebody else’s tree, you are most likely using
182 remote-tracking branches (refs/heads/origin in traditional layout, or
183 refs/remotes/origin/master in the separate-remote layout). You usually
184 want the tags from the other end.
185 On the other hand, if you are fetching because you would want a
187 one-shot merge from somebody else, you typically do not want to get
188 tags from there. This happens more often for people near the toplevel
189 but not limited to them. Mere mortals when pulling from each other do
190 not necessarily want to automatically get private anchor point tags
191 from the other person.
192 Often, "please pull" messages on the mailing list just provide two
194 pieces of information: a repo URL and a branch name; this is designed
195 to be easily cut&pasted at the end of a git fetch command line:
196 Linus, please pull from
198 git://git..../proj.git master
200 to get the following updates...
202 becomes:
205 $ git pull git://git..../proj.git master
207 In such a case, you do not want to automatically follow the other
210 person’s tags.
211 One important aspect of Git is its distributed nature, which largely
213 means there is no inherent "upstream" or "downstream" in the system. On
214 the face of it, the above example might seem to indicate that the tag
215 namespace is owned by the upper echelon of people and that tags only
216 flow downwards, but that is not the case. It only shows that the usage
217 pattern determines who are interested in whose tags.
218 A one-shot pull is a sign that a commit history is now crossing the
220 boundary between one circle of people (e.g. "people who are primarily
221 interested in the networking part of the kernel") who may have their
222 own set of tags (e.g. "this is the third release candidate from the
223 networking group to be proposed for general consumption with 2.6.21
224 release") to another circle of people (e.g. "people who integrate
225 various subsystem improvements"). The latter are usually not interested
226 in the detailed tags used internally in the former group (that is what
227 "internal" means). That is why it is desirable not to follow tags
228 automatically in this case.
229 It may well be that among networking people, they may want to exchange
231 the tags internal to their group, but in that workflow they are most
232 likely tracking each other’s progress by having remote-tracking
233 branches. Again, the heuristic to automatically follow such tags is a
234 good thing.
235 On Backdating Tags
237 If you have imported some changes from another VCS and would like to
238 add tags for major releases of your work, it is useful to be able to
239 specify the date to embed inside of the tag object; such data in the
240 tag object affects, for example, the ordering of tags in the gitweb
241 interface.
242 To set the date used in future tag objects, set the environment
244 variable GIT_COMMITTER_DATE (see the later discussion of possible
245 values; the most common form is "YYYY-MM-DD HH:MM").
246 For example:
248 $ GIT_COMMITTER_DATE="2006-10-02 10:31" git tag -s v1.0.1
250
253 The GIT_AUTHOR_DATE, GIT_COMMITTER_DATE environment variables support
254 the following date formats:
255 Git internal format
257 It is <unix timestamp> <timezone offset>, where <unix timestamp> is
258 the number of seconds since the UNIX epoch. <timezone offset> is a
259 positive or negative offset from UTC. For example CET (which is 2
260 hours ahead UTC) is +0200.
261 RFC 2822
263 The standard email format as described by RFC 2822, for example
264 Thu, 07 Apr 2005 22:13:13 +0200.
265 ISO 8601
267 Time and date specified by the ISO 8601 standard, for example
268 2005-04-07T22:13:13. The parser accepts a space instead of the T
269 character as well.
270 Note
272 In addition, the date part is accepted in the following
273 formats: YYYY.MM.DD, MM/DD/YYYY and DD.MM.YYYY.
274
276 git-check-ref-format(1).
277
279 Part of the git(1) suite
280Git 1.8.3.1 11/19/2018 GIT-TAG(1)