|
1 .. Copyright © 2014 Greg Ward <greg@gerg.ca> |
|
2 |
|
3 ------------------ |
|
4 Evolve: User Guide |
|
5 ------------------ |
|
6 |
|
7 .. contents:: |
|
8 |
|
9 Life without ``evolve`` |
|
10 ----------------------- |
|
11 |
|
12 Before we dive into learning about ``evolve``, let's look into some |
|
13 features of core Mercurial that interact with ``evolve``. ``commit`` |
|
14 affects ``evolve``, and ``evolve`` modifies how ``commit --amend`` |
|
15 works. |
|
16 |
|
17 Example 1: Commit a new changeset |
|
18 ================================= |
|
19 |
|
20 To create a new changeset, simply run ``hg commit`` as usual. |
|
21 ``evolve`` does not change the behaviour of ``commit`` at all. |
|
22 |
|
23 However, it's important to understand that new changesets are in the |
|
24 *draft* phase by default: they are mutable. This means that they can |
|
25 be modified by Mercurial's existing history-editing commands |
|
26 (``rebase``, ``histedit``, etc.), and also by the ``evolve`` |
|
27 extension. Specifically, ``evolve`` adds a number of commands that can |
|
28 be used to modify history: ``amend``, ``uncommit``, ``prune``, |
|
29 ``fold``, and ``evolve``. Generally speaking, changesets remain in |
|
30 *draft* phase until they are pushed to another repository, at which |
|
31 point they enter *public* phase. :: |
|
32 |
|
33 $ hg commit -m 'implement feature X' |
|
34 $ hg phase -r . |
|
35 1: draft |
|
36 |
|
37 (Strictly speaking, changesets only become public when they are pushed |
|
38 to a *publishing* repository. But all repositories are publishing by |
|
39 default; you have to explicitly configure repositories to be |
|
40 *non-publishing*. Non-publishing repositories are an advanced topic |
|
41 which we'll see when we get to `sharing mutable history`_.) |
|
42 |
|
43 .. _`sharing mutable history`: sharing.html |
|
44 |
|
45 Example 2: Amend a changeset (traditional) |
|
46 ========================================== |
|
47 |
|
48 Imagine you've just committed a new changeset, and then you discover a |
|
49 mistake. Maybe you forgot to run the tests and a failure slipped in. |
|
50 You want to modify history so that you push one perfect changeset, |
|
51 rather than one flawed changeset followed by an "oops" commit. (Or |
|
52 perhaps you made a typo in the commit message—this is really feature |
|
53 *Y*, not feature X. You can't fix that with a followup commit.) |
|
54 |
|
55 This is actually trivial with plain vanilla Mercurial since 2.2: fix |
|
56 your mistake and run :: |
|
57 |
|
58 $ hg commit --amend -m 'implement feature Y' |
|
59 |
|
60 to create a new, amended changeset. The drawback of doing this with |
|
61 vanilla Mercurial is that your original, flawed, changeset is removed |
|
62 from the repository. This is *unsafe* history editing. It's probably |
|
63 not too serious if all you did was fix a syntax error, but still. |
|
64 |
|
65 .. figure:: figures/figure-ug01.svg |
|
66 |
|
67 Figure 1: unsafe history modification with core Mercurial (not |
|
68 using ``evolve``): the original revision 1 is destroyed. |
|
69 |
|
70 (Incidentally, Mercurial's traditional history modification mechanism |
|
71 isn't *really* unsafe: any changeset(s) removed from the repository |
|
72 are kept in a backup directory, so you can manually restore them later |
|
73 if you change your mind. But it's awkward and inconvenient compared to |
|
74 the features provided by ``evolve`` and changeset obsolescence.) |
|
75 |
|
76 Life with ``evolve`` (basic usage) |
|
77 ---------------------------------- |
|
78 |
|
79 Once you enable the ``evolve`` extension, a number of features are |
|
80 available to you. First, we're going to explore several examples of |
|
81 painless, trouble-free history modification. |
|
82 |
|
83 Example 3: Amend a changeset (with ``evolve``) |
|
84 ============================================== |
|
85 |
|
86 Outwardly, amending a changeset with ``evolve`` can look exactly the |
|
87 same as it does with core Mercurial (example 2):: |
|
88 |
|
89 $ hg commit --amend -m 'implement feature Y' |
|
90 |
|
91 Alternately, you can use the new ``amend`` command added by |
|
92 ``evolve``:: |
|
93 |
|
94 $ hg amend -m 'implement feature Y' |
|
95 |
|
96 (``hg amend`` is nearly synonymous with ``hg commit --amend``. The |
|
97 difference is that ``hg amend`` reuses the existing commit message by |
|
98 default, whereas ``hg commit --amend`` runs your editor if you don't |
|
99 pass ``-m`` or ``-l``.) |
|
100 |
|
101 Under the hood, though, things are quite different. Mercurial has |
|
102 simply marked the old changeset *obsolete*, replacing it with a new |
|
103 one. We'll explore what this means in detail later, after working |
|
104 through a few more examples. |
|
105 |
|
106 Example 4: Prune an unwanted changeset |
|
107 ====================================== |
|
108 |
|
109 Sometimes you make a change, and then decide it was such a bad idea |
|
110 that you don't want anyone to know about it. Or maybe it was a |
|
111 debugging hack that you needed to keep around for a while, but do not |
|
112 intend to ever push publicly. :: |
|
113 |
|
114 $ echo 'debug hack' >> file1.c |
|
115 $ hg commit -m 'debug hack' |
|
116 |
|
117 In either case, ``hg prune`` is the answer. ``prune`` simply marks |
|
118 changesets obsolete without creating any new changesets to replace |
|
119 them:: |
|
120 |
|
121 $ hg prune . |
|
122 1 changesets pruned |
|
123 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
124 working directory now at 934359450037 |
|
125 |
|
126 Outwardly, it appears that your “debug hack” commit never happened; |
|
127 we're right back where we started:: |
|
128 |
|
129 $ hg parents --template '{rev}:{node|short} {desc|firstline}\n' |
|
130 3:934359450037 implement feature Y |
|
131 |
|
132 In reality, though, the “debug hack” is still there, obsolete and hidden. |
|
133 |
|
134 Example 5: Uncommit changes to certain files |
|
135 ============================================ |
|
136 |
|
137 Occasionally you commit more than you intended: perhaps you made |
|
138 unrelated changes to different files, and thus intend to commit |
|
139 different files separately. :: |
|
140 |
|
141 $ echo 'relevant' >> file1.c |
|
142 $ echo 'irrelevant' >> file2.c |
|
143 |
|
144 If you forget to specify filenames on the ``commit`` command line, |
|
145 Mercurial commits all those changes together:: |
|
146 |
|
147 $ hg commit -m 'fix bug 234' # oops: too many files |
|
148 |
|
149 Luckily, this mistake is easy to fix with ``uncommit``:: |
|
150 |
|
151 $ hg uncommit file2.c |
|
152 $ hg status |
|
153 M file2.c |
|
154 |
|
155 Let's verify that the replacement changeset looks right (i.e., |
|
156 modifies only ``file1.c``):: |
|
157 |
|
158 $ hg parents --template '{rev}:{node|short} {desc|firstline}\n{files}\n' |
|
159 6:c8defeecf7a4 fix bug 234 |
|
160 file1.c |
|
161 |
|
162 As before, the original flawed changeset is still there, but obsolete |
|
163 and hidden. It won't be exchanged with other repositories by ``push``, |
|
164 ``pull``, or ``clone``. |
|
165 |
|
166 Example 6: Fold multiple changesets together into one |
|
167 ===================================================== |
|
168 |
|
169 If you're making extensive changes to fragile source code, you might |
|
170 commit more frequently than normal so that you can fallback on a |
|
171 known good state if one step goes badly. :: |
|
172 |
|
173 $ echo step1 >> file1.c |
|
174 $ hg commit -m 'step 1' # revision 7 |
|
175 $ echo step2 >> file1.c |
|
176 $ hg commit -m 'step 2' # revision 8 |
|
177 $ echo step3 >> file2.c |
|
178 $ hg commit -m 'step 3' # revision 9 |
|
179 |
|
180 At the end of such a sequence, you often end up with a series of small |
|
181 changesets that are tedious to review individually. It might make more |
|
182 sense to combine them into a single changeset using the ``fold`` |
|
183 command. |
|
184 |
|
185 To make sure we pass the right revisions to ``fold``, let's review the |
|
186 changesets we just created, from revision 7:: |
|
187 |
|
188 $ hg log --template '{rev}:{node|short} {desc|firstline}\n' -r 7:: |
|
189 7:05e61aab8294 step 1 |
|
190 8:be6d5bc8e4cc step 2 |
|
191 9:35f432d9f7c1 step 3 |
|
192 |
|
193 and fold them:: |
|
194 |
|
195 $ hg fold -m 'fix bug 64' -r 7:: |
|
196 3 changesets folded |
|
197 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
198 |
|
199 This time, Mercurial marks three changesets obsolete, replacing them |
|
200 all with a single *successor*. |
|
201 |
|
202 (You might be familiar with this operation under other names, like |
|
203 *squash* or *collapse*.) |
|
204 |
|
205 Changeset obsolescence under the hood |
|
206 ------------------------------------- |
|
207 |
|
208 So far, everything has gone just fine: we haven't run into merge |
|
209 conflicts or other trouble. Before we start exploring advanced usage |
|
210 that can run into trouble, let's step back and see what happens when |
|
211 Mercurial marks changesets obsolete. That will make it much easier to |
|
212 understand the more advanced use cases we'll see later. |
|
213 |
|
214 When you have the ``evolve`` extension enabled, all history |
|
215 modification uses the same underlying mechanism: the original |
|
216 changesets are marked *obsolete* and replaced by zero or more |
|
217 *successors*. The obsolete changesets are the *precursors* of their |
|
218 successors. This applies equally to built-in commands (``commit |
|
219 --amend``), commands added by ``evolve`` (``amend``, ``prune``, |
|
220 ``uncommit``, ``fold``), and commands provided by other extensions |
|
221 (``rebase``, ``histedit``). |
|
222 |
|
223 Another way of looking at it is that obsolescence is second-order |
|
224 version control, i.e. the history of your history. We'll cover this in |
|
225 more detail (and mathematical precision) in the `concepts`_ guide. |
|
226 |
|
227 .. _`concepts`: concepts.html |
|
228 |
|
229 Under the hood: Amend a changeset |
|
230 ================================= |
|
231 |
|
232 Consider Example 2, amending a changeset with ``evolve``. We saw above |
|
233 that you can do this using the exact same command-line syntax as core |
|
234 Mercurial, namely ``hg commit --amend``. But the implementation is |
|
235 quite different, and Figure 2 shows how. |
|
236 |
|
237 .. figure:: figures/figure-ug02.svg |
|
238 |
|
239 Figure 2: safe history modification using ``evolve``: the original |
|
240 revision 1 is preserved as an obsolete changeset. (The "temporary |
|
241 amend commit", marked with T, is an implementation detail stemming |
|
242 from limitations in Mercurial's current merge machinery. Future |
|
243 versions of Mercurial will not create them.) |
|
244 |
|
245 In this case, the obsolete changesets are also *hidden*. That is the |
|
246 usual end state for obsolete changesets. But many scenarios result in |
|
247 obsolete changesets that are still visible, which indicates your |
|
248 history modification work is not yet done. We'll see examples of that |
|
249 later, when we cover advanced usage. |
|
250 |
|
251 |
|
252 Understanding revision numbers and hidden changesets |
|
253 ==================================================== |
|
254 |
|
255 As the name implies, hidden changesets are normally not visible. If |
|
256 you run ``hg log`` on the repository from Figure 2, Mercurial will |
|
257 show revisions 0 and 3, but not 1 and 2. That's something you don't |
|
258 see with plain vanilla Mercurial—normally, revision *N* is always |
|
259 followed by revision *N* + 1. |
|
260 |
|
261 This is just the visible manifestation of hidden changesets. If |
|
262 revision 0 is followed by revision 3, that means there are two hidden |
|
263 changesets, 1 and 2, in between. |
|
264 |
|
265 To see those hidden changesets, use the ``--hidden`` option:: |
|
266 |
|
267 $ hg --hidden log --graph --template '{rev}:{node|short} {desc|firstline}\n' |
|
268 @ 3:934359450037 implement feature Y |
|
269 | |
|
270 | x 2:6c5f78d5d467 temporary amend commit for fe0ecd3bd2a4 |
|
271 | | |
|
272 | x 1:fe0ecd3bd2a4 implement feature Y |
|
273 |/ |
|
274 o 0:08c4b6f4efc8 init |
|
275 |
|
276 Note that changeset IDs are still the permanent, immutable identifier |
|
277 for changesets. Revision numbers are, as ever, a handy shorthand that |
|
278 work in your local repository, but cannot be used across repositories. |
|
279 They also have the useful property of showing when there are hidden |
|
280 changesets lurking under the covers, which is why this document uses |
|
281 revision numbers. |
|
282 |
|
283 |
|
284 Under the hood: Prune an unwanted changeset |
|
285 =========================================== |
|
286 |
|
287 ``prune`` (example 4 above) is the simplest history modification |
|
288 command provided by ``evolve``. All it does is mark the specified |
|
289 changeset(s) obsolete, with no successor/precursor relationships |
|
290 involved. (If the working directory parent was one of the obsolete |
|
291 changesets, ``prune`` updates back to a suitable ancestor.) |
|
292 |
|
293 .. figure:: figures/figure-ug03.svg |
|
294 |
|
295 Figure 3: pruning a changeset marks it obsolete with no successors. |
|
296 |
|
297 Under the hood: Uncommit changes to certain files |
|
298 ================================================= |
|
299 |
|
300 In one sense, ``uncommit`` is a simplified version of ``amend``. Like |
|
301 ``amend``, it obsoletes one changeset and leaves it with a single |
|
302 successor. Unlike ``amend``, there is no ugly "temporary amend commit" |
|
303 cluttering up the repository. |
|
304 |
|
305 In another sense, ``uncommit`` is the inverse of ``amend``: ``amend`` |
|
306 takes any uncommitted changes in the working dir and “adds” |
|
307 them to the working directory's parent changeset. (In reality, of |
|
308 course, it creates a successor changeset, marking the original |
|
309 obsolete.) In contrast, ``uncommit`` takes some changes in the working |
|
310 directory's parent and moves them to the working dir, creating a new |
|
311 successor changeset in the process. Figure 4 illustrates. |
|
312 |
|
313 .. figure:: figures/figure-ug04.svg |
|
314 |
|
315 Figure 4: uncommit moves some of the changes from the working |
|
316 directory parent into the working dir, preserving the remaining |
|
317 changes as a new successor changeset. (N.B. revision 4 is not shown |
|
318 here because it was marked obsolete in the previous example.) |
|
319 |
|
320 |
|
321 Under the hood: Fold multiple changesets together into one |
|
322 ========================================================== |
|
323 |
|
324 The last basic example is folding multiple changesets into one, which |
|
325 marks multiple changesets obsolete, replacing them all with a single |
|
326 successor. |
|
327 |
|
328 .. figure:: figures/figure-ug05.svg |
|
329 |
|
330 Figure 5: fold combines multiple changesets into a single |
|
331 successor, marking the original (folded) changesets obsolete. |
|
332 |
|
333 |
|
334 Obsolete is not hidden |
|
335 ====================== |
|
336 |
|
337 So far, every obsolete changeset we have seen is also hidden. However, |
|
338 these are *not* the same thing—that's why they have different names. |
|
339 It's entirely possible to have obsolete changesets that are not |
|
340 hidden. We'll see examples of that soon, when we create *unstable* |
|
341 changesets. |
|
342 |
|
343 Note that all hidden changesets are obsolete: hidden is a subset of |
|
344 obsolete. |
|
345 |
|
346 |
|
347 Life with ``evolve`` (advanced usage) |
|
348 ------------------------------------- |
|
349 |
|
350 Now that you've got a solid understanding of how ``evolve`` works in |
|
351 concert with changeset obsolescence, let's explore some more advanced |
|
352 scenarios. All of these scenarios will involve *unstable* changesets, |
|
353 which is an unavoidable consequence of obsolescence. What really sets |
|
354 ``evolve`` apart from other history modification mechanisms is the |
|
355 fact that it recognizes troubles like unstable changesets and provides |
|
356 a consistent way for you to get out of trouble. |
|
357 |
|
358 (Incidentally, there are two other types of trouble that changesets |
|
359 can get into with ``evolve``: they may be *divergent* or *bumped*. |
|
360 Both of those states are more likely to occur when `sharing mutable |
|
361 history`_, so we won't see them in this user guide.) |
|
362 |
|
363 .. _`sharing mutable history`: sharing.html |
|
364 |
|
365 |
|
366 Example 7: Amend an older changeset |
|
367 =================================== |
|
368 |
|
369 Sometimes you don't notice your mistakes until after you have |
|
370 committed new changesets on top of them. :: |
|
371 |
|
372 $ hg commit -m 'fix bug 17' # rev 11 (mistake here) |
|
373 $ hg commit -m 'cleanup' # rev 12 |
|
374 $ hg commit -m 'feature 23' # rev 13 |
|
375 |
|
376 Traditionally, your only option is to commit an "oops" changeset that |
|
377 fixes your mistake. That works, of course, but it makes you look bad: |
|
378 you made a mistake, and the record of that mistake is recorded in |
|
379 history for all eternity. (If the mistake was in the commit message, |
|
380 too bad: you cannot fix it.) |
|
381 |
|
382 More subtly, there now exist changesets that are *worse* than what |
|
383 came before—the code no longer builds, the tests don't pass, or |
|
384 similar. Anyone reviewing these patches will waste time on the error |
|
385 in the earlier patch, and then the correction later on. |
|
386 |
|
387 You can avoid all this by amending the bad changeset and *evolving* |
|
388 subsequent history. Here's how it works, assuming you have just |
|
389 committed revision 13 and noticed the mistake in revision 11:: |
|
390 |
|
391 $ hg update 11 |
|
392 [...fix mistake...] |
|
393 $ hg amend |
|
394 |
|
395 At this point, revision 11 is *obsolete* and revisions 12 and 13—the |
|
396 descendants of 11—are in a funny state: they are *unstable*. |
|
397 |
|
398 .. figure:: figures/figure-ug06.svg |
|
399 |
|
400 Figure 6: amending a changeset with descendants means the amended |
|
401 changeset is obsolete but remains visible; its non-obsolete |
|
402 descendants are *unstable*. The temporary amend commit, revision |
|
403 14, is hidden because it has no non-obsolete descendants. |
|
404 |
|
405 All non-obsolete descendants of an obsolete changeset are unstable. An |
|
406 interesting consequence of this is that revision 11 is still visible, |
|
407 even though it is obsolete. Obsolete changesets with non-obsolete |
|
408 descendants are not hidden. |
|
409 |
|
410 The fix is to *evolve* history:: |
|
411 |
|
412 $ hg evolve --all |
|
413 |
|
414 This is a separate step, not automatically part of ``hg amend``, |
|
415 because there might be conflicts. If your amended changeset modifies a |
|
416 file that one of its descendants also modified, Mercurial has to fire |
|
417 up your merge tool to resolve the conflict. More importantly, you have |
|
418 to switch contexts from "writing code" to "resolving conflicts". That |
|
419 can be an expensive context switch, so Mercurial lets you decide when |
|
420 to do it. |
|
421 |
|
422 The end state, after ``evolve`` finishes, is that the original |
|
423 revisions (11-13) are obsolete and hidden. Their successor revisions |
|
424 (15-17) replace them. |
|
425 |
|
426 .. figure:: figures/figure-ug07.svg |
|
427 |
|
428 Figure 7: evolve your repository (``hg evolve --all``) to take care |
|
429 of instability. Unstable changesets become obsolete, and are |
|
430 replaced by successors just like the amended changeset was. |
|
431 |
|
432 Example 8: Prune an older changeset |
|
433 =================================== |
|
434 |
|
435 Let's say you've just committed the following changesets:: |
|
436 |
|
437 $ hg commit -m 'useful work' # rev 18 |
|
438 $ hg commit -m 'debug hack' # rev 19 |
|
439 $ hg commit -m 'more work' # rev 20 |
|
440 |
|
441 You want to drop revision 19, but keep 18 and 20. No problem:: |
|
442 |
|
443 $ hg prune 19 |
|
444 1 changesets pruned |
|
445 1 new unstable changesets |
|
446 |
|
447 As above, this leaves your repository in a funny intermediate state: |
|
448 revision 20 is the non-obsolete descendant of obsolete revision 19. |
|
449 That is, revision 20 is unstable. |
|
450 |
|
451 .. figure:: figures/figure-ug08.svg |
|
452 |
|
453 Figure 8: ``hg prune`` marks a changeset obsolete without creating |
|
454 a successor. Just like with ``hg amend``, non-obsolete descendants |
|
455 of the pruned changeset are now unstable. |
|
456 |
|
457 As before, the solution to unstable changesets is to evolve your |
|
458 repository:: |
|
459 |
|
460 $ hg evolve --all |
|
461 |
|
462 This rebases revision 20 on top of 18 as the new revision 21, leaving |
|
463 19 and 20 obsolete and hidden: |
|
464 |
|
465 .. figure:: figures/figure-ug09.svg |
|
466 |
|
467 Figure 9: once again, ``hg evolve --all`` takes care of instability. |
|
468 |
|
469 Example 9: Uncommit files from an older changeset (discard changes) |
|
470 ======================================================================= |
|
471 |
|
472 As in example 5, let's say you accidentally commit some unrelated |
|
473 changes together. Unlike example 5, you don't notice your mistake |
|
474 immediately, but commit a new changeset on top of the bad one. :: |
|
475 |
|
476 $ echo 'this fixes bug 53' >> file1.c |
|
477 $ echo 'debug hack' >> file2.c |
|
478 $ hg commit -m 'fix bug 53' # rev 22 (oops) |
|
479 $ echo 'and this handles bug 67' >> file1.c |
|
480 $ hg commit -m 'fix bug 67' # rev 23 (fine) |
|
481 |
|
482 As with ``amend``, you need to travel back in time and repair revision |
|
483 22, leaving your changes to ``file2.c`` back in the working |
|
484 directory:: |
|
485 |
|
486 $ hg update 22 |
|
487 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
488 $ hg uncommit file2.c |
|
489 1 new unstable changesets |
|
490 $ hg status |
|
491 M file2.c |
|
492 |
|
493 Now your repository has unstable changesets, so you need to evolve it. |
|
494 But ``hg evolve`` requires a clean working directory to resolve merge |
|
495 conflicts, so you need to decide what to do with ``file2.c``. |
|
496 |
|
497 In this case, the change to ``file2.c`` was a temporary debugging |
|
498 hack, so we can discard it and immediately evolve the instability away:: |
|
499 |
|
500 $ hg revert file2.c |
|
501 $ hg evolve --all |
|
502 move:[23] fix bug 67 |
|
503 atop:[24] fix bug 53 |
|
504 |
|
505 Figure 10 illustrates the whole process. |
|
506 |
|
507 .. figure:: figures/figure-ug10.svg |
|
508 |
|
509 Figure 10: ``hg uncommit`` of a changeset with descendants results |
|
510 in instability *and* a dirty working directory, both of which must |
|
511 be dealt with. |
|
512 |
|
513 |
|
514 Example 10: Uncommit files to an older changeset (keep changes) |
|
515 =================================================================== |
|
516 |
|
517 This is very similar to example 9. The difference that this time, our |
|
518 change to ``file2.c`` is valuable enough to commit, making things a |
|
519 bit more complicated. The setup is nearly identical:: |
|
520 |
|
521 $ echo 'fix a bug' >> file1.c |
|
522 $ echo 'useful but unrelated' >> file2.c |
|
523 $ hg commit -u dan -d '11 0' -m 'fix a bug' # rev 26 (oops) |
|
524 $ echo 'new feature' >> file1.c |
|
525 $ hg commit -u dan -d '12 0' -m 'new feature' # rev 27 (fine) |
|
526 |
|
527 As before, we update back to the flawed changeset (this time, |
|
528 revision 26) and ``uncommit``, leaving uncommitted changes to |
|
529 ``file2.c`` in the working dir:: |
|
530 |
|
531 $ hg update -q 26 |
|
532 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
|
533 $ hg uncommit -q file2.c # obsoletes rev 26, creates rev 28 |
|
534 1 new unstable changesets |
|
535 $ hg status |
|
536 M file2.c |
|
537 |
|
538 This time, let's save that useful change before evolving:: |
|
539 |
|
540 $ hg commit -m 'useful tweak' # rev 29 |
|
541 |
|
542 Figure 11 shows the story so far: ``uncommit`` obsoleted revision 26 |
|
543 and created revision 28, the successor of 26. Then we committed |
|
544 revision 29, a child of 28. We still have to deal with the unstable |
|
545 revision 27. |
|
546 |
|
547 .. figure:: figures/figure-ug11.svg |
|
548 |
|
549 Figure 11: Uncommitting a file and then committing that change |
|
550 separately will soon result in a two-headed repository. |
|
551 |
|
552 This is where things get tricky. As usual when a repository has |
|
553 unstable changesets, we want to evolve it:: |
|
554 |
|
555 $ hg evolve --all |
|
556 |
|
557 The problem is that ``hg evolve`` rebases revision 27 onto revision |
|
558 28, creating 30 (the successor of 27). This is entirely logical: 27 |
|
559 was the child of 26, and 26's successor is 28. So of course 27's |
|
560 successor (30) should be the child of 26's successor (28). |
|
561 Unfortunately, that leaves us with a two-headed repository: |
|
562 |
|
563 .. figure:: figures/figure-ug12.svg |
|
564 |
|
565 Figure 12: ``evolve`` takes care of unstable changesets; it does |
|
566 not solve all the world's problems. |
|
567 |
|
568 As usual when faced with a two-headed repository, you can either merge |
|
569 or rebase. It's up to you. |
|
570 |
|
571 |
|
572 Example 11: Recover an obsolete changeset |
|
573 ========================================= |
|
574 |
|
575 Sometimes you might obsolete a changeset, and then change your mind. You'll |
|
576 probably start looking for an “unobsolete” command to restore a changeset |
|
577 to normal state. For complicated implementation reasons, that command |
|
578 doesn't exist. (If you have already pushed an obsolescence marker to |
|
579 another repo, then Mercurial would need a way to revoke that remote |
|
580 obsolesence marker. That's a hard problem.) |
|
581 |
|
582 Instead, ``evolve`` provides a ``touch`` command to resurrect an |
|
583 obsolete changeset. An unexpected quirk: you almost certainly need to |
|
584 use ``--hidden``, since obsolete changesets tend to be hidden, and you |
|
585 can't reference a hidden changeset otherwise. Typical usage thus looks |
|
586 like :: |
|
587 |
|
588 $ hg --hidden touch REV |
|
589 |
|
590 This creates a new, normal changeset which is the same as ``REV``—except |
|
591 with a different changeset ID. The new changeset will have the same parent |
|
592 as ``REV``, and will be a successor of ``REV``. |
|
593 |
|
594 The current implementation of ``hg touch`` is not ideal, and is likely to |
|
595 change in the future. Consider the history in Figure 12, where revision 27 |
|
596 is obsolete and the child of 26, also obsolete. If we ``hg touch 27``, that |
|
597 creates a new revision which is a non-obsolete child of 26—i.e., it is |
|
598 unstable. It's also *divergent*, another type of trouble that we'll learn |
|
599 about in the `next section`_. |
|
600 |
|
601 .. _`next section`: sharing.html |