Mercurial > evolve
comparison docs/sharing.rst @ 2932:0afd41ac31d2
sharing: edit pass
author | Ryan McElroy <rmcelroy@fb.com> |
---|---|
date | Wed, 30 Aug 2017 17:32:32 +0200 |
parents | b0b8cc3064b0 |
children |
comparison
equal
deleted
inserted
replaced
2931:83d2c9637e89 | 2932:0afd41ac31d2 |
---|---|
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 *remote* 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 |
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 |
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:: |
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 |