|
1 ============== |
|
2 Topic Tutorial |
|
3 ============== |
|
4 |
|
5 .. This test file is also supposed to be able to compile as a rest file. |
|
6 |
|
7 |
|
8 .. Some Setup:: |
|
9 |
|
10 $ . "$TESTDIR/testlib/topic_setup.sh" |
|
11 $ hg init server |
|
12 $ cd server |
|
13 $ cat >> .hg/hgrc << EOF |
|
14 > [ui] |
|
15 > user= Shopping Master |
|
16 > EOF |
|
17 $ cat >> shopping << EOF |
|
18 > Spam |
|
19 > Whizzo butter |
|
20 > Albatross |
|
21 > Rat (rather a lot) |
|
22 > Jugged fish |
|
23 > Blancmange |
|
24 > Salmon mousse |
|
25 > EOF |
|
26 $ hg commit -A -m "Shopping list" |
|
27 adding shopping |
|
28 $ cd .. |
|
29 $ hg clone server client |
|
30 updating to branch default |
|
31 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
32 $ cd client |
|
33 $ cat >> .hg/hgrc << EOF |
|
34 > [ui] |
|
35 > user= Tutorial User |
|
36 > EOF |
|
37 |
|
38 Topic branches are lightweight branches which disappear when changes are |
|
39 finalized (move to the public phase). They can help users to organise and share |
|
40 their unfinished work. |
|
41 |
|
42 Topic Basics |
|
43 ============ |
|
44 |
|
45 Let's says we use Mercurial to manage our shopping list:: |
|
46 |
|
47 $ hg log --graph |
|
48 @ changeset: 0:38da43f0a2ea |
|
49 tag: tip |
|
50 user: test |
|
51 date: Thu Jan 01 00:00:00 1970 +0000 |
|
52 summary: Shopping list |
|
53 |
|
54 |
|
55 We are about to do some edition to this list and would like to do them within |
|
56 a topic. Creating a new topic is done using the ``topic`` command:: |
|
57 |
|
58 $ hg topic food |
|
59 |
|
60 As for named branch, our topic is active but it does not contains any changesets yet:: |
|
61 |
|
62 $ hg topic |
|
63 * food |
|
64 $ hg summary |
|
65 parent: 0:38da43f0a2ea tip |
|
66 Shopping list |
|
67 branch: default |
|
68 commit: (clean) |
|
69 update: (current) |
|
70 topic: food |
|
71 $ hg log --graph |
|
72 @ changeset: 0:38da43f0a2ea |
|
73 tag: tip |
|
74 user: test |
|
75 date: Thu Jan 01 00:00:00 1970 +0000 |
|
76 summary: Shopping list |
|
77 |
|
78 |
|
79 Our next commit will be part of the active topic:: |
|
80 |
|
81 $ cat >> shopping << EOF |
|
82 > Egg |
|
83 > Suggar |
|
84 > Vinegar |
|
85 > Oil |
|
86 > EOF |
|
87 $ hg commit -m "adding condiments" |
|
88 $ hg log --graph --rev 'topic("food")' |
|
89 @ changeset: 1:13900241408b |
|
90 | tag: tip |
|
91 ~ topic: food |
|
92 user: test |
|
93 date: Thu Jan 01 00:00:00 1970 +0000 |
|
94 summary: adding condiments |
|
95 |
|
96 |
|
97 And future commit will be part of that topic too:: |
|
98 |
|
99 $ cat >> shopping << EOF |
|
100 > Bananas |
|
101 > Pear |
|
102 > Apple |
|
103 > EOF |
|
104 $ hg commit -m "adding fruits" |
|
105 $ hg log --graph --rev 'topic("food")' |
|
106 @ changeset: 2:287de11b401f |
|
107 | tag: tip |
|
108 | topic: food |
|
109 | user: test |
|
110 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
111 | summary: adding fruits |
|
112 | |
|
113 o changeset: 1:13900241408b |
|
114 | topic: food |
|
115 ~ user: test |
|
116 date: Thu Jan 01 00:00:00 1970 +0000 |
|
117 summary: adding condiments |
|
118 |
|
119 |
|
120 We can get a compact view of the content of our topic using the ``stack`` command:: |
|
121 |
|
122 $ hg stack |
|
123 ### topic: food |
|
124 ### branch: default |
|
125 t2@ adding fruits (current) |
|
126 t1: adding condiments |
|
127 ^ Shopping list |
|
128 |
|
129 The topic desactivate when we update away from it:: |
|
130 |
|
131 $ hg up default |
|
132 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
133 $ hg topic |
|
134 food |
|
135 |
|
136 Note that ``default`` (name of the branch) now refers to the tipmost changeset of default without a topic:: |
|
137 |
|
138 $ hg log --graph |
|
139 o changeset: 2:287de11b401f |
|
140 | tag: tip |
|
141 | topic: food |
|
142 | user: test |
|
143 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
144 | summary: adding fruits |
|
145 | |
|
146 o changeset: 1:13900241408b |
|
147 | topic: food |
|
148 | user: test |
|
149 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
150 | summary: adding condiments |
|
151 | |
|
152 @ changeset: 0:38da43f0a2ea |
|
153 user: test |
|
154 date: Thu Jan 01 00:00:00 1970 +0000 |
|
155 summary: Shopping list |
|
156 |
|
157 |
|
158 And updating back to the topic reactivate it:: |
|
159 |
|
160 $ hg up food |
|
161 switching to topic food |
|
162 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
163 $ hg topic |
|
164 * food |
|
165 |
|
166 The name used for updating does not affect the activation of the topic, updating to a revision part of a topic will activate it in all cases:: |
|
167 |
|
168 $ hg up default |
|
169 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
170 $ hg up --rev 'desc("condiments")' |
|
171 switching to topic food |
|
172 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
173 $ hg topic |
|
174 * food |
|
175 |
|
176 .. server side activity:: |
|
177 |
|
178 $ cd ../server/ |
|
179 $ cat > shopping << EOF |
|
180 > T-Shirt |
|
181 > Trousers |
|
182 > Spam |
|
183 > Whizzo butter |
|
184 > Albatross |
|
185 > Rat (rather a lot) |
|
186 > Jugged fish |
|
187 > Blancmange |
|
188 > Salmon mousse |
|
189 > EOF |
|
190 $ hg commit -A -m "Adding clothes" |
|
191 $ cd ../client |
|
192 |
|
193 Topic will also affect rebase and merge destination. Let's pull the latest update from the main server:: |
|
194 |
|
195 $ hg pull |
|
196 pulling from $TESTTMP/server |
|
197 searching for changes |
|
198 adding changesets |
|
199 adding manifests |
|
200 adding file changes |
|
201 added 1 changesets with 1 changes to 1 files (+1 heads) |
|
202 (run 'hg heads' to see heads) |
|
203 $ hg log -G |
|
204 o changeset: 3:6104862e8b84 |
|
205 | tag: tip |
|
206 | parent: 0:38da43f0a2ea |
|
207 | user: test |
|
208 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
209 | summary: Adding clothes |
|
210 | |
|
211 | o changeset: 2:287de11b401f |
|
212 | | topic: food |
|
213 | | user: test |
|
214 | | date: Thu Jan 01 00:00:00 1970 +0000 |
|
215 | | summary: adding fruits |
|
216 | | |
|
217 | @ changeset: 1:13900241408b |
|
218 |/ topic: food |
|
219 | user: test |
|
220 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
221 | summary: adding condiments |
|
222 | |
|
223 o changeset: 0:38da43f0a2ea |
|
224 user: test |
|
225 date: Thu Jan 01 00:00:00 1970 +0000 |
|
226 summary: Shopping list |
|
227 |
|
228 |
|
229 The topic head will not be considered when merge from the new head of the branch:: |
|
230 |
|
231 $ hg up default |
|
232 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
233 $ hg merge |
|
234 abort: branch 'default' has one head - please merge with an explicit rev |
|
235 (run 'hg heads' to see all heads) |
|
236 [255] |
|
237 |
|
238 But the topic will see that branch head as a valid destination:: |
|
239 |
|
240 $ hg up food |
|
241 switching to topic food |
|
242 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
243 $ hg rebase |
|
244 rebasing 1:13900241408b "adding condiments" |
|
245 merging shopping |
|
246 rebasing 2:287de11b401f "adding fruits" |
|
247 merging shopping |
|
248 $ hg log --graph |
|
249 @ changeset: 5:2d50db8b5b4c |
|
250 | tag: tip |
|
251 | topic: food |
|
252 | user: test |
|
253 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
254 | summary: adding fruits |
|
255 | |
|
256 o changeset: 4:4011b46eeb33 |
|
257 | topic: food |
|
258 | user: test |
|
259 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
260 | summary: adding condiments |
|
261 | |
|
262 o changeset: 3:6104862e8b84 |
|
263 | parent: 0:38da43f0a2ea |
|
264 | user: test |
|
265 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
266 | summary: Adding clothes |
|
267 | |
|
268 o changeset: 0:38da43f0a2ea |
|
269 user: test |
|
270 date: Thu Jan 01 00:00:00 1970 +0000 |
|
271 summary: Shopping list |
|
272 |
|
273 |
|
274 The topic information will fade out when we publish the changesets:: |
|
275 |
|
276 $ hg topic |
|
277 food |
|
278 $ hg push |
|
279 pushing to $TESTTMP/server |
|
280 searching for changes |
|
281 adding changesets |
|
282 adding manifests |
|
283 adding file changes |
|
284 added 2 changesets with 2 changes to 1 files |
|
285 2 new obsolescence markers |
|
286 $ hg topic |
|
287 $ hg log --graph |
|
288 @ changeset: 5:2d50db8b5b4c |
|
289 | tag: tip |
|
290 | user: test |
|
291 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
292 | summary: adding fruits |
|
293 | |
|
294 o changeset: 4:4011b46eeb33 |
|
295 | user: test |
|
296 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
297 | summary: adding condiments |
|
298 | |
|
299 o changeset: 3:6104862e8b84 |
|
300 | parent: 0:38da43f0a2ea |
|
301 | user: test |
|
302 | date: Thu Jan 01 00:00:00 1970 +0000 |
|
303 | summary: Adding clothes |
|
304 | |
|
305 o changeset: 0:38da43f0a2ea |
|
306 user: test |
|
307 date: Thu Jan 01 00:00:00 1970 +0000 |
|
308 summary: Shopping list |
|
309 |
|
310 $ hg up default |
|
311 0 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
312 |
|
313 Working with Multiple Topics |
|
314 ============================ |
|
315 |
|
316 In the above example, topic are not bring much benefit since you only have one |
|
317 line of developement. Topic start to be more useful when you have to work on |
|
318 multiple features are the same time. |
|
319 |
|
320 We might go shopping in a hardware store in the same go, so let's add some |
|
321 tools to the shopping list withing a new topic:: |
|
322 |
|
323 $ hg topic tools |
|
324 $ echo hammer >> shopping |
|
325 $ hg ci -m 'Adding hammer' |
|
326 $ echo saw >> shopping |
|
327 $ hg ci -m 'Adding saw' |
|
328 $ echo drill >> shopping |
|
329 $ hg ci -m 'Adding drill' |
|
330 |
|
331 But are not sure to actually go in the hardward store, so in the meantime, we |
|
332 want to extend the list with drinks. We go back to the official default branch |
|
333 and start a new topic:: |
|
334 |
|
335 $ hg up default |
|
336 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
337 $ hg topic drinks |
|
338 $ echo 'apple juice' >> shopping |
|
339 $ hg ci -m 'Adding apple juice' |
|
340 $ echo 'orange juice' >> shopping |
|
341 $ hg ci -m 'Adding orange juice' |
|
342 |
|
343 We now have two topics:: |
|
344 |
|
345 $ hg topic |
|
346 * drinks |
|
347 tools |
|
348 |
|
349 The information ``hg stack`` command adapt to the active topic:: |
|
350 |
|
351 $ hg stack |
|
352 ### topic: drinks |
|
353 ### branch: default |
|
354 t2@ Adding orange juice (current) |
|
355 t1: Adding apple juice |
|
356 ^ adding fruits |
|
357 $ hg up tools |
|
358 switching to topic tools |
|
359 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
360 $ hg stack |
|
361 ### topic: tools |
|
362 ### branch: default |
|
363 t3@ Adding drill (current) |
|
364 t2: Adding saw |
|
365 t1: Adding hammer |
|
366 ^ adding fruits |
|
367 |
|
368 They are seen as independant branch by Mercurial. No rebase or merge betwen them will be attempted by default:: |
|
369 |
|
370 $ hg rebase |
|
371 nothing to rebase |
|
372 [1] |
|
373 |
|
374 .. server activity:: |
|
375 |
|
376 $ cd ../server |
|
377 $ hg up |
|
378 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
379 $ mv shopping foo |
|
380 $ echo 'Coat' > shopping |
|
381 $ cat foo >> shopping |
|
382 $ hg ci -m 'add a coat' |
|
383 $ echo 'Coat' > shopping |
|
384 $ echo 'Shoes' >> shopping |
|
385 $ cat foo >> shopping |
|
386 $ hg rm foo |
|
387 not removing foo: file is untracked |
|
388 [1] |
|
389 $ hg ci -m 'add a pair of shoes' |
|
390 $ cd ../client |
|
391 |
|
392 Lets see what other people did in the mean time:: |
|
393 |
|
394 $ hg pull |
|
395 pulling from $TESTTMP/server |
|
396 searching for changes |
|
397 adding changesets |
|
398 adding manifests |
|
399 adding file changes |
|
400 added 2 changesets with 2 changes to 1 files (+1 heads) |
|
401 (run 'hg heads' to see heads) |
|
402 |
|
403 There is new changes! We can simply use ``hg rebase`` to update our changeset on top of the latest:: |
|
404 |
|
405 $ hg rebase |
|
406 rebasing 6:183984ef46d1 "Adding hammer" |
|
407 merging shopping |
|
408 rebasing 7:cffff85af537 "Adding saw" |
|
409 merging shopping |
|
410 rebasing 8:34255b455dac "Adding drill" |
|
411 merging shopping |
|
412 |
|
413 But what about the other topic? You can use 'hg topic --verbose' to see information about them:: |
|
414 |
|
415 $ hg topic --verbose |
|
416 drinks (on branch: default, 2 changesets, 2 behind) |
|
417 tools (on branch: default, 3 changesets) |
|
418 |
|
419 The "2 behind" is telling you that there is 2 new changesets on the named branch of the topic. You need to merge or rebase to incorporate them. |
|
420 |
|
421 Pushing that topic would create a new heads will be prevented:: |
|
422 |
|
423 $ hg push --rev drinks |
|
424 pushing to $TESTTMP/server |
|
425 searching for changes |
|
426 abort: push creates new remote head 70dfa201ed73! |
|
427 (merge or see "hg help push" for details about pushing new heads) |
|
428 [255] |
|
429 |
|
430 |
|
431 Even after a rebase Pushing all active topics at the same time will complains about the multiple heads it would create on that branch:: |
|
432 |
|
433 $ hg rebase -b drinks |
|
434 rebasing 9:8dfa45bd5e0c "Adding apple juice" |
|
435 merging shopping |
|
436 rebasing 10:70dfa201ed73 "Adding orange juice" |
|
437 merging shopping |
|
438 switching to topic tools |
|
439 $ hg push |
|
440 pushing to $TESTTMP/server |
|
441 searching for changes |
|
442 abort: push creates new remote head 4cd7c1591a67! |
|
443 (merge or see "hg help push" for details about pushing new heads) |
|
444 [255] |
|
445 |
|
446 Publishing only one of them is allowed (as long as it does not create a new branch head has we just saw in the previous case):: |
|
447 |
|
448 $ hg push -r drinks |
|
449 pushing to $TESTTMP/server |
|
450 searching for changes |
|
451 adding changesets |
|
452 adding manifests |
|
453 adding file changes |
|
454 added 2 changesets with 2 changes to 1 files |
|
455 2 new obsolescence markers |
|
456 |
|
457 The publishing topic has now vanished, and the one still draft is now marked as "behind":: |
|
458 |
|
459 $ hg topic --verbose |
|
460 * tools (on branch: default, 3 changesets, 2 behind) |
|
461 $ hg stack |
|
462 ### topic: tools |
|
463 ### branch: default, 2 behind |
|
464 t3@ Adding drill (current) |
|
465 t2: Adding saw |
|
466 t1: Adding hammer |
|
467 ^ add a pair of shoes |
|
468 |