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>] <name> [<head>]
10 git-tag -d <name>...
11 git-tag [-n [<num>]] -l [<pattern>]
12 git-tag -v <name>...
13
15 Adds a tag reference in .git/refs/tags/
16 Unless -f is given, the tag must not yet exist in .git/refs/tags/
18 directory.
19 If one of -a, -s, or -u <key-id> is passed, the command creates a tag
21 object, and requires the tag message. Unless -m <msg> or -F <file> is
22 given, an editor is started for the user to type in the tag message.
23 Otherwise just the SHA1 object name of the commit object is written
25 (i.e. a lightweight tag).
26 A GnuPG signed tag object will be created when -s or -u <key-id> is
28 used. When -u <key-id> is not used, the committer identity for the
29 current user is used to find the GnuPG key for signing.
30
32 -a
33 Make an unsigned, annotated tag object
34 -s
36 Make a GPG-signed tag, using the default e-mail address´s key
37 -u <key-id>
39 Make a GPG-signed tag, using the given key
40 -f
42 Replace an existing tag with the given name (instead of failing)
43 -d
45 Delete existing tags with the given names.
46 -v
48 Verify the gpg signature of the given tag names.
49 -n <num>
51 <num> specifies how many lines from the annotation, if any, are
52 printed when using -l. The default is not to print any annotation
53 lines. If no number is given to -n, only the first line is printed.
54 -l <pattern>
56 List tags with names that match the given pattern (or all if no
57 pattern is given). Typing "git tag" without arguments, also lists
58 all tags.
59 -m <msg>
61 Use the given tag message (instead of prompting)
62 -F <file>
64 Take the tag message from the given file. Use - to read the message
65 from the standard input.
66
68 By default, git-tag in sign-with-default mode (-s) will use your
69 committer identity (of the form "Your Name <your@email.address>") to
70 find a key. If you want to use a different default key, you can specify
71 it in the repository configuration as follows:
72 [user]
76 signingkey = <gpg-key-id>
77
80 On Re-tagging
81 What should you do when you tag a wrong commit and you would want to
82 re-tag?
83 If you never pushed anything out, just re-tag it. Use "-f" to replace
85 the old one. And you´re done.
86 But if you have pushed things out (or others could just read your
88 repository directly), then others will have already seen the old tag.
89 In that case you can do one of two things:
90 1. The sane thing. Just admit you screwed up, and use a different
93 name. Others have already seen one tag-name, and if you keep the
94 same name, you may be in the situation that two people both have
95 "version X", but they actually have different "X"´s. So just call
96 it "X.1" and be done with it.
97 2. The insane thing. You really want to call the new version "X" too,
99 even though others have already seen the old one. So just use "git
100 tag -f" again, as if you hadn´t already published the old one.
101 However, Git does not (and it should not)change tags behind users back.
102 So if somebody already got the old tag, doing a "git pull" on your tree
103 shouldn´t just make them overwrite the old one.
104 If somebody got a release tag from you, you cannot just change the tag
106 for them by updating your own one. This is a big security issue, in
107 that people MUST be able to trust their tag-names. If you really want
108 to do the insane thing, you need to just fess up to it, and tell people
109 that you messed up. You can do that by making a very public
110 announcement saying:
111 Ok, I messed up, and I pushed out an earlier version tagged as X. I
115 then fixed something, and retagged the *fixed* tree as X again.
116 If you got the wrong tag, and want the new one, please delete
118 the old one and fetch the new one by doing:
119 git tag -d X
121 git fetch origin tag X
122 to get my updated tag.
124 You can test which tag you have by doing
126 git rev-parse X
128 which should return 0123456789abcdef.. if you have the new version.
130 Sorry for inconvenience.
132 Does this seem a bit complicated? It should be. There is no way that it
134 would be correct to just "fix" it behind peoples backs. People need to
135 know that their tags might have been changed.
136 On Automatic following
138 If you are following somebody else´s tree, you are most likely using
139 tracking branches (refs/heads/origin in traditional layout, or
140 refs/remotes/origin/master in the separate-remote layout). You usually
141 want the tags from the other end.
142 On the other hand, if you are fetching because you would want a
144 one-shot merge from somebody else, you typically do not want to get
145 tags from there. This happens more often for people near the toplevel
146 but not limited to them. Mere mortals when pulling from each other do
147 not necessarily want to automatically get private anchor point tags
148 from the other person.
149 You would notice "please pull" messages on the mailing list says repo
151 URL and branch name alone. This is designed to be easily cut&pasted to
152 "git fetch" command line:
153 Linus, please pull from
157 git://git..../proj.git master
159 to get the following updates...
161 becomes:
163 $ git pull git://git..../proj.git master
167 In such a case, you do not want to automatically follow other´s tags.
169 One important aspect of git is it is distributed, and being distributed
171 largely means there is no inherent "upstream" or "downstream" in the
172 system. On the face of it, the above example might seem to indicate
173 that the tag namespace is owned by upper echelon of people and tags
174 only flow downwards, but that is not the case. It only shows that the
175 usage pattern determines who are interested in whose tags.
176 A one-shot pull is a sign that a commit history is now crossing the
178 boundary between one circle of people (e.g. "people who are primarily
179 interested in networking part of the kernel") who may have their own
180 set of tags (e.g. "this is the third release candidate from the
181 networking group to be proposed for general consumption with 2.6.21
182 release") to another circle of people (e.g. "people who integrate
183 various subsystem improvements"). The latter are usually not interested
184 in the detailed tags used internally in the former group (that is what
185 "internal" means). That is why it is desirable not to follow tags
186 automatically in this case.
187 It may well be that among networking people, they may want to exchange
189 the tags internal to their group, but in that workflow they are most
190 likely tracking with each other´s progress by having tracking branches.
191 Again, the heuristic to automatically follow such tags is a good thing.
192
194 Written by Linus Torvalds <torvalds@osdl.org>, Junio C Hamano
195 <junkio@cox.net> and Chris Wright <chrisw@osdl.org>.
196
198 Documentation by David Greaves, Junio C Hamano and the git-list
199 <git@vger.kernel.org>.
200
202 Part of the git(7) suite
203Git 1.5.3.3 10/09/2007 GIT-TAG(1)