@matheusbsbs / matheus-bagliano / commits / 4853534e18
Fork 0

Add discussion section to git-tag documentation.

Signed-off-by: Junio C Hamano <junkio@cox.net>

Junio C Hamano committed Feb 11, 2007 at 22:29 UTC 4853534e180c237331cb8395fe87ff6e09bbcf21
1 file changed +131
Documentation/git-tag.txt
+131
@@ -80,6 +80,137 @@ it in the repository configuration as follows:
80 [user]
81 signingkey = <gpg-key-id>
82
83 +
84 +DISCUSSION
85 +----------
86 +
87 +On Re-tagging
88 +~~~~~~~~~~~~~
89 +
90 +What should you do when you tag a wrong commit and you would
91 +want to re-tag?
92 +
93 +If you never pushed anything out, just re-tag it. Use "-f" to
94 +replace the old one. And you're done.
95 +
96 +But if you have pushed things out (or others could just read
97 +your repository directly), then others will have already seen
98 +the old tag. In that case you can do one of two things:
99 +
100 +. The sane thing.
101 +Just admit you screwed up, and use a different name. Others have
102 +already seen one tag-name, and if you keep the same name, you
103 +may be in the situation that two people both have "version X",
104 +but they actually have 'different' "X"'s. So just call it "X.1"
105 +and be done with it.
106 +
107 +. The insane thing.
108 +You really want to call the new version "X" too, 'even though'
109 +others have already seen the old one. So just use "git tag -f"
110 +again, as if you hadn't already published the old one.
111 +
112 +However, Git does *not* (and it should not)change tags behind
113 +users back. So if somebody already got the old tag, doing a "git
114 +pull" on your tree shouldn't just make them overwrite the old
115 +one.
116 +
117 +If somebody got a release tag from you, you cannot just change
118 +the tag for them by updating your own one. This is a big
119 +security issue, in that people MUST be able to trust their
120 +tag-names. If you really want to do the insane thing, you need
121 +to just fess up to it, and tell people that you messed up. You
122 +can do that by making a very public announcement saying:
123 +
124 +------------
125 +Ok, I messed up, and I pushed out an earlier version tagged as X. I
126 +then fixed something, and retagged the *fixed* tree as X again.
127 +
128 +If you got the wrong tag, and want the new one, please delete
129 +the old one and fetch the new one by doing:
130 +
131 + git tag -d X
132 + git fetch origin tag X
133 +
134 +to get my updated tag.
135 +
136 +You can test which tag you have by doing
137 +
138 + git rev-parse X
139 +
140 +which should return 0123456789abcdef.. if you have the new version.
141 +
142 +Sorry for inconvenience.
143 +------------
144 +
145 +Does this seem a bit complicated? It *should* be. There is no
146 +way that it would be correct to just "fix" it behind peoples
147 +backs. People need to know that their tags might have been
148 +changed.
149 +
150 +
151 +On Automatic following
152 +~~~~~~~~~~~~~~~~~~~~~~
153 +
154 +If you are following somebody else's tree, you are most likely
155 +using tracking branches (`refs/heads/origin` in traditional
156 +layout, or `refs/remotes/origin/master` in the separate-remote
157 +layout). You usually want the tags from the other end.
158 +
159 +On the other hand, if you are fetching because you would want a
160 +one-shot merge from somebody else, you typically do not want to
161 +get tags from there. This happens more often for people near
162 +the toplevel but not limited to them. Mere mortals when pulling
163 +from each other do not necessarily want to automatically get
164 +private anchor point tags from the other person.
165 +
166 +You would notice "please pull" messages on the mailing list says
167 +repo URL and branch name alone. This is designed to be easily
168 +cut&pasted to "git fetch" command line:
169 +
170 +------------
171 +Linus, please pull from
172 +
173 + git://git..../proj.git master
174 +
175 +to get the following updates...
176 +------------
177 +
178 +becomes:
179 +
180 +------------
181 +$ git pull git://git..../proj.git master
182 +------------
183 +
184 +In such a case, you do not want to automatically follow other's
185 +tags.
186 +
187 +One important aspect of git is it is distributed, and being
188 +distributed largely means there is no inherent "upstream" or
189 +"downstream" in the system. On the face of it, the above
190 +example might seem to indicate that the tag namespace is owned
191 +by upper echelon of people and tags only flow downwards, but
192 +that is not the case. It only shows that the usage pattern
193 +determines who are interested in whose tags.
194 +
195 +A one-shot pull is a sign that a commit history is now crossing
196 +the boundary between one circle of people (e.g. "people who are
197 +primarily interested in networking part of the kernel") who may
198 +have their own set of tags (e.g. "this is the third release
199 +candidate from the networking group to be proposed for general
200 +consumption with 2.6.21 release") to another circle of people
201 +(e.g. "people who integrate various subsystem improvements").
202 +The latter are usually not interested in the detailed tags used
203 +internally in the former group (that is what "internal" means).
204 +That is why it is desirable not to follow tags automatically in
205 +this case.
206 +
207 +It may well be that among networking people, they may want to
208 +exchange the tags internal to their group, but in that workflow
209 +they are most likely tracking with each other's progress by
210 +having tracking branches. Again, the heuristic to automatically
211 +follow such tags is a good thing.
212 +
213 +
214 Author
215 ------
216 Written by Linus Torvalds <torvalds@osdl.org>,