43 passing yet—just ``hg amend`` when they are. And you can transfer |
43 passing yet—just ``hg amend`` when they are. And you can transfer |
44 those half-baked changesets between repositories to try things out on |
44 those half-baked changesets between repositories to try things out on |
45 your test server before anything is carved in stone. |
45 your test server before anything is carved in stone. |
46 |
46 |
47 A less common scenario is multiple developers sharing mutable history, |
47 A less common scenario is multiple developers sharing mutable history, |
48 typically for code review. We'll cover this scenario later. But first, |
48 typically for code review. We'll cover this scenario later. First, we |
49 single-user sharing. |
49 will cover single-user sharing. |
50 |
50 |
51 Sharing with a single developer |
51 Sharing with a single developer |
52 ------------------------------- |
52 ------------------------------- |
53 |
53 |
54 Publishing and non-publishing repositories |
54 Publishing and non-publishing repositories |
55 ========================================== |
55 ========================================== |
56 |
56 |
57 The key to shared mutable history is to keep your changesets in |
57 The key to shared mutable history is to keep your changesets in |
58 *draft* phase as you pass them around. Recall that by default, ``hg |
58 *draft* phase as you pass them around. Recall that by default, |
59 push`` promotes changesets from *draft* to *public*, and public |
59 ``hg push`` promotes changesets from *draft* to *public*, and public |
60 changesets are immutable. You can change this behaviour by |
60 changesets are immutable. You can change this behaviour by |
61 reconfiguring the *target* repository so that it is non-publishing. |
61 reconfiguring the *remote* repository so that it is non-publishing. |
62 (Short version: set ``phases.publish`` to ``false``. Long version |
62 (Short version: set ``phases.publish`` to ``false``. Long version |
63 follows.) |
63 follows.) |
64 |
64 |
65 Setting up |
65 Setting up |
66 ========== |
66 ========== |
88 we'll develop in ``dev-repo``, push to ``test-repo``, test and polish |
88 we'll develop in ``dev-repo``, push to ``test-repo``, test and polish |
89 there, and push to ``public``. |
89 there, and push to ``public``. |
90 |
90 |
91 The key to shared mutable history is to make the target repository, in |
91 The key to shared mutable history is to make the target repository, in |
92 this case ``test-repo``, non-publishing. And, of course, we have to |
92 this case ``test-repo``, non-publishing. And, of course, we have to |
93 enable ``evolve`` in both ``test-repo`` and ``dev-repo``. |
93 enable the ``evolve`` extension in both ``test-repo`` and ``dev-repo``. |
94 |
94 |
95 First, edit the configuration for ``test-repo``:: |
95 First, edit the configuration for ``test-repo``:: |
96 |
96 |
97 $ hg -R test-repo config --edit --local |
97 $ hg -R test-repo config --edit --local |
98 |
98 |
201 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
201 1 files updated, 0 files merged, 0 files removed, 0 files unresolved |
202 |
202 |
203 As seen in figure 3, this transfers the new changeset *and* the |
203 As seen in figure 3, this transfers the new changeset *and* the |
204 obsolescence marker for revision 1. However, it does *not* transfer |
204 obsolescence marker for revision 1. However, it does *not* transfer |
205 the temporary amend commit, because it is hidden. Push and pull |
205 the temporary amend commit, because it is hidden. Push and pull |
206 transfer obsolesence markers between repositories, but they do not |
206 transfer obsolescence markers between repositories, but they do not |
207 transfer hidden changesets. |
207 transfer hidden changesets. |
208 |
208 |
209 [figure SG03: dev-repo grows new rev 2:60ff, marks 1:f649 obsolete] |
209 [figure SG03: dev-repo grows new rev 2:60ff, marks 1:f649 obsolete] |
210 |
210 |
211 Because of this deliberately incomplete synchronization, revision |
211 Because of this deliberately incomplete synchronization, revision |
249 hidden changesets on push and pull. |
249 hidden changesets on push and pull. |
250 |
250 |
251 .. _`concept guide`: concepts.html |
251 .. _`concept guide`: concepts.html |
252 |
252 |
253 So the picture in ``public`` is much simpler than in either |
253 So the picture in ``public`` is much simpler than in either |
254 ``dev-repo`` or ``test-repo``. Neither our missteps nor our amendments |
254 ``dev-repo`` or ``test-repo``. Neither of our missteps nor our amendments |
255 are publicly visible, just the final, beautifully polished changeset: |
255 are publicly visible, just the final, beautifully polished changeset: |
256 |
256 |
257 [figure SG05: public repo with rev 0:0dc9, 1:de61, both public] |
257 [figure SG05: public repo with rev 0:0dc9, 1:de61, both public] |
258 |
258 |
259 There is one important step left to do. Because we pushed from |
259 There is one important step left to do. Because we pushed from |
506 Mercurial with ``evolve`` is a powerful tool, and using powerful tools |
506 Mercurial with ``evolve`` is a powerful tool, and using powerful tools |
507 can have consequences. (You can cut yourself badly with a sharp knife, |
507 can have consequences. (You can cut yourself badly with a sharp knife, |
508 but every competent chef keeps several around. Ever try to chop onions |
508 but every competent chef keeps several around. Ever try to chop onions |
509 with a spoon?) |
509 with a spoon?) |
510 |
510 |
511 In the user guide, we saw examples of *unstable* changesets, which are |
511 In the user guide, we saw examples of *unstbale* changesets, which are |
512 the most common type of troubled changeset. (Recall that a |
512 the most common type of troubled changeset. (Recall that a |
513 non-obsolete changeset with obsolete ancestors is unstable.) |
513 non-obsolete changeset with obsolete ancestors is an orphan.) |
514 |
514 |
515 Two other types of trouble can happen: *divergent* and *bumped* |
515 Two other types of troubles can happen: *divergent* and |
516 changesets. Both are more likely with shared mutable history, |
516 *bumped* changesets. Both are more likely with shared mutable |
517 especially mutable history shared by multiple developers. |
517 history, especially mutable history shared by multiple developers. |
518 |
518 |
519 Setting up |
519 Setting up |
520 ========== |
520 ========== |
521 |
521 |
522 For these examples, we're going to use a slightly different workflow: |
522 For these examples, we're going to use a slightly different workflow: |
558 |
558 |
559 Example 6: Divergent changesets |
559 Example 6: Divergent changesets |
560 =============================== |
560 =============================== |
561 |
561 |
562 When an obsolete changeset has two successors, those successors are |
562 When an obsolete changeset has two successors, those successors are |
563 *divergent*. One way to get into such a situation is by failing to |
563 *divergent*. One way to get into such a situation is by failing |
564 communicate with your teammates. Let's see how that might happen. |
564 to communicate with your teammates. Let's see how that might happen. |
565 |
565 |
566 First, we'll have Bob commit a bug fix that could still be improved:: |
566 First, we'll have Bob commit a bug fix that could still be improved:: |
567 |
567 |
568 $ cd bob |
568 $ cd bob |
569 $ echo 'pretty good fix' >> file1 |
569 $ echo 'pretty good fix' >> file1 |
619 (``internal:other``) that will take Alice's changes over Bob's. (You |
619 (``internal:other``) that will take Alice's changes over Bob's. (You |
620 might wonder why Bob wouldn't prefer his own changes by using |
620 might wonder why Bob wouldn't prefer his own changes by using |
621 ``internal:local``. He's avoiding a `bug`_ in ``evolve`` that occurs |
621 ``internal:local``. He's avoiding a `bug`_ in ``evolve`` that occurs |
622 when evolving divergent changesets using ``internal:local``.) |
622 when evolving divergent changesets using ``internal:local``.) |
623 |
623 |
|
624 # XXX this link does not work |
624 .. _`bug`: https://bitbucket.org/marmoute/mutable-history/issue/48/ |
625 .. _`bug`: https://bitbucket.org/marmoute/mutable-history/issue/48/ |
625 |
626 |
626 ** STOP HERE: WORK IN PROGRESS ** |
627 ** STOP HERE: WORK IN PROGRESS ** |
627 |
628 |
628 Bumped changesets: only one gets on the plane |
629 Phase-divergence: when a rewritten changeset is made public |
629 ============================================= |
630 =========================================================== |
630 |
631 |
631 If two people show up at the airport with tickets for the same seat on |
632 If Alice and Bob are collaborating on some mutable |
632 the same plane, only one of them gets on the plane. The would-be |
|
633 traveller left behind in the airport terminal is said to have been |
|
634 *bumped*. |
|
635 |
|
636 Similarly, if Alice and Bob are collaborating on some mutable |
|
637 changesets, it's possible to get into a situation where an otherwise |
633 changesets, it's possible to get into a situation where an otherwise |
638 worthwhile changeset cannot be pushed to the public repository; it is |
634 worthwhile changeset cannot be pushed to the public repository; it is |
639 bumped by an alternative changeset that happened to get there first. |
635 *phase-divergent* with another changeset that was made public first. |
640 Let's demonstrate one way this could happen. |
636 Let's demonstrate one way this could happen. |
641 |
637 |
642 It starts with Alice committing a bug fix. Right now, we don't yet |
638 It starts with Alice committing a bug fix. Right now, we don't yet |
643 know if this bug fix is good enough to push to the public repository, |
639 know if this bug fix is good enough to push to the public repository, |
644 but it's good enough for Alice to commit. :: |
640 but it's good enough for Alice to commit. :: |
674 [...] |
670 [...] |
675 added 1 changesets with 1 changes to 1 files |
671 added 1 changesets with 1 changes to 1 files |
676 |
672 |
677 This introduces a contradiction: in Bob's repository, changeset 2:e011 |
673 This introduces a contradiction: in Bob's repository, changeset 2:e011 |
678 (his copy of Alice's fix) is obsolete, since Bob amended it. But in |
674 (his copy of Alice's fix) is obsolete, since Bob amended it. But in |
679 Alice's repository (and ``public``), that changeset is public: it is |
675 Alice's repository (and the ``public`` repository), that changeset is |
680 immutable, carved in stone for all eternity. No changeset can be both |
676 public: it is immutable, carved in stone for all eternity. No changeset |
681 obsolete and public, so Bob is in for a surprise the next time he |
677 can be both obsolete and public, so Bob is in for a surprise the next |
682 pulls from ``public``:: |
678 time he pulls from ``public``:: |
683 |
679 |
684 $ cd ../bob |
680 $ cd ../bob |
685 $ hg pull -q -u |
681 $ hg pull -q -u |
686 1 new bumped changesets |
682 1 new phase-divergent changesets |
687 |
683 |
688 Figure 7 shows what just happened to Bob's repository: changeset |
684 Figure 7 shows what just happened to Bob's repository: changeset |
689 2:e011 is now public, so it can't be obsolete. When that changeset was |
685 2:e011 is now public, so it can't be obsolete. When that changeset was |
690 obsolete, it made perfect sense for it to have a successor, namely |
686 obsolete, it made perfect sense for it to have a successor, namely |
691 Bob's amendment of Alice's fix (changeset 4:fe88). But it's illogical |
687 Bob's amendment of Alice's fix (changeset 4:fe88). But it's illogical |
692 for a public changeset to have a successor, so 4:fe88 is in trouble: |
688 for a public changeset to have a successor, so 4:fe88 is troubled: |
693 it has been *bumped*. |
689 it has become *bumped*. |
694 |
690 |
695 [figure SG07: 2:e011 now public not obsolete, 4:fe88 now bumped] |
691 [figure SG07: 2:e011 now public not obsolete, 4:fe88 now bumped] |
696 |
692 |
697 As usual when there's trouble in your repository, the solution is to |
693 As usual when there's trouble in your repository, the solution is to |
698 evolve it:: |
694 evolve it:: |
699 |
695 |
700 $ hg evolve --all |
696 $ hg evolve --all |
701 |
697 |
702 Figure 8 illustrate's Bob's repository after evolving away the bumped |
698 Figure 8 illustrates Bob's repository after evolving away the bumped |
703 changeset. Ignoring the obsolete changesets, Bob now has a nice, |
699 changeset. Ignoring the obsolete changesets, Bob now has a nice, |
704 clean, simple history. His amendment of Alice's bug fix lives on, as |
700 clean, simple history. His amendment of Alice's bug fix lives on, as |
705 changeset 5:227d—albeit with a software-generated commit message. (Bob |
701 changeset 5:227d—albeit with a software-generated commit message. (Bob |
706 should probably amend that changeset to improve the commit message.) |
702 should probably amend that changeset to improve the commit message.) |
707 But the important thing is that his repository no longer has any |
703 But the important thing is that his repository no longer has any |
716 user can do wonderful things with it, much more wonderful than with a |
712 user can do wonderful things with it, much more wonderful than with a |
717 dull knife (never mind a rusty spoon). At the same time, an |
713 dull knife (never mind a rusty spoon). At the same time, an |
718 inattentive or careless user can do harm to himself or others. |
714 inattentive or careless user can do harm to himself or others. |
719 Mercurial with ``evolve`` goes to great lengths to limit the harm you |
715 Mercurial with ``evolve`` goes to great lengths to limit the harm you |
720 can do by trying to handle all possible types of “troubled” |
716 can do by trying to handle all possible types of “troubled” |
721 changesets. But having a first-aid kit nearby does not excuse you from |
717 changesets. Nevertheless, having a first-aid kit nearby does not mean |
722 being careful with sharp knives. |
718 you should stop being careful with sharp knives. |
723 |
719 |
724 Mutable history shared across multiple repositories by a single |
720 Mutable history shared across multiple repositories by a single |
725 developer is a natural extension of this model. Once you are used to |
721 developer is a natural extension of this model. Once you are used to |
726 using a single sharp knife on its own, it's pretty straightforward to |
722 using a single sharp knife on its own, it's pretty straightforward to |
727 chop onions and mushrooms using the same knife, or to alternate |
723 chop onions and mushrooms using the same knife, or to alternate |