repository (see the `user guide`_), you can move up to the next level:

*shared* mutable history. ``evolve`` lets you push and pull draft

changesets between repositories along with their obsolescence markers.

This opens up a number of interesting possibilities.

Using Mercurial with ``evolve`` to share mutable history solves these

problems. As with single-repository ``evolve``, you can commit

We'll work through an example with three local repositories, although

in the real world they'd most likely be on three different computers.

First, the ``public`` repository is where tested, polished changesets

live, and it is where you synchronize with the rest of your team. ::

We'll need two clones where work gets done, ``test-repo`` and

``dev-repo``::

The key to shared mutable history is to make the target repository, in

this case ``test-repo``, non-publishing. And, of course, we have to

enable ``evolve`` in both ``test-repo`` and ``dev-repo``.

  [figure SG02: test-repo has rev 0:0dc9 public, rev 1:f649, 2:2a03 obsolete, rev 3:60ff draft; dev-repo same as in SG01]

  [...]

  added 1 changesets with 1 changes to 1 files (+1 heads)

  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

the temporary amend commit, because it is hidden. Push and pull

transfer hidden changesets.

amendments—was actually pushed. Again, Mercurial doesn't transfer

hidden changesets on push and pull.

  [...]

  no changes found

Even though no *changesets* were pulled, Mercurial still pulled

obsolescence markers from ``test-repo``.

Sharing with multiple developers: code review

---------------------------------------------

Now that you know how to share your own mutable history across

multiple computers, you might be wondering if it makes sense to share

mutable history with others. It does, but you have to be careful, stay

alert, and *communicate* with your peers.

A good way to start is with code review: Alice commits a draft

changeset that Bob can review. Bob sends his comments to Alice, and

she amends it until Bob is satisfied. Meanwhile, Bob is also

committing draft changesets for Alice to review, amending until she is

satisfied. Once a particular changeset passes review, the respective

author (Alice or Bob) pushes it to the public repository.

Setting up

==========

To demonstrate, let's start with the ``public`` repository as we left

it in the last example, with two immutable changesets (figure 5

above). We'll clone a ``review`` repository from it, and then Alice

and Bob will both clone from ``review``. ::

  $ hg clone public review

  updating to branch default

  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg clone review alice

  updating to branch default

  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

  $ hg clone review bob

  updating to branch default

  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

We need to configure Alice's and Bob's working repositories similar to

``test-repo``, i.e. make them non-publishing and enable ``evolve``.

First, edit Alice's configuration with ::

  $ hg -R alice config --edit --local

and add ::

  [extensions]

  evolve = /path/to/mutable-history/hgext/evolve.py

Then add the same text to Bob's repository configuration::

  $ hg -R bob config --edit --local

Example 3: Alice commits and amends a draft fix

===============================================

We'll start by following Alice working on a bug fix. We're going to

use bookmarks to make it easier to understand multiple branch heads in

the ``review`` repository, so Alice starts off by creating a bookmark

and committing her first attempt at a fix::

  $ hg bookmark bug15

  $ echo 'fix' > file2

  $ hg commit -A -u alice -m 'fix bug 15 (v1)'

  adding file2

Note the unorthodox "(v1)" in the commit message. We're just using

that to make this tutorial easier to follow; it's not something we'd

recommend in real life.

Of course Alice wouldn't commit unless her fix worked to her

satisfaction, so it must be time to solicit a code review. She does

this by pushing to the ``review`` repository::

  $ hg push -B bug15

  [...]

  added 1 changesets with 1 changes to 1 files

  exporting bookmark bug15

(The use of ``-B`` is important to ensure that we only push the

bookmarked head, and that the bookmark itself is pushed. See this

`guide to bookmarks`_, especially the `Sharing Bookmarks`_ section, if

you're not familiar with bookmarks.)

.. _`guide to bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/

.. _`Sharing Bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/#sharing-bookmarks

Some time passes, and Alice receives her code review. (It might be by

email, telephone, or carrier pigeon: it doesn't matter, as it's

outside the scope of Mercurial.) As a result, Alice revises her fix

and submits it for a second review::

  $ echo 'Fix.' > file2

  $ hg amend -m 'fix bug 15 (v2)'

  $ hg push

  [...]

  added 1 changesets with 1 changes to 1 files (+1 heads)

  updating bookmark bug15

Figure 6 shows the state of the ``review`` repository at this point.

  [figure SG06: rev 2:fn1e is alice's obsolete v1, rev 3:cbdf is her v2; both children of rev 1:de61]

After a hard morning of bug fixing, Alice stops for lunch. Let's see

what Bob has been up to.

Example 4: Bob implements and publishes a new feature

=====================================================

In the meantime, Bob has been working on a new feature. Like Alice,

he'll use a bookmark to track his work, and he'll push that bookmark

to the ``review`` repository, so that reviewers know which changesets

to review. ::

  $ cd ../bob

  $ echo 'stuff' > file1

  $ hg bookmark featureX

  $ hg commit -u bob -m 'implement feature X (v1)'

  $ hg push -B featureX

  [...]

  added 1 changesets with 1 changes to 1 files (+1 heads)

  exporting bookmark featureX

When Bob receives his code review, he improves his implementation a

bit, amends, and submits the resulting changeset for review::

  $ echo 'do stuff' > file1

  $ hg amend -m 'implement feature X (v2)'

  $ hg push

  [...]

  added 1 changesets with 1 changes to 1 files (+1 heads)

  updating bookmark featureX

Unfortunately, that still doesn't pass muster. Bob's reviewer insists

on proper capitalization and punctuation. ::

  $ echo 'Do stuff.' > file1

  $ hg amend -m 'implement feature X (v3)'

On the bright side, the second review said, "Go ahead and publish once

you fix that." So Bob immediately publishes his third attempt::

  $ hg push ../public

  [...]

  added 1 changesets with 1 changes to 1 files

Bob also has to update the ``review`` repository: right now it doesn't

have his latest amendment ("v3", revision 6:540b), and it doesn't know

that the precursor of that changeset ("v2", revision 5:0eb7) is

obsolete. ::

  $ hg push ../review

  [...]

  added 1 changesets with 1 changes to 1 files (+1 heads)

  updating bookmark featureX

Figure 7 shows the result of Bob's work in both ``review`` and

``public``.

  [figure SG07: review includes alice's draft work on bug 15, as well as Bob's v1, v2, and v3 changes for feature X: v1 and v2 obsolete, v3 public. public contains only the final, public implementation of feature X]

Incidentally, it's important that Bob push to ``public`` *before*

``review``. If he pushed to ``review`` first, then revision 6:540b

would still be in *draft* phase in ``review``, but it would be

*public* in both Bob's local repository and the ``public`` repository.

That could lead to confusion at some point, which is easily avoided by

pushing first to ``public``.

Example 5: Alice integrates and publishes

=========================================

Finally, Alice gets back from lunch and sees that the carrier pigeon

with her second review has arrived (or maybe she just has it in her

email inbox). Alice's amended changeset has passed review, so she

pushes her fix to ``public``::

  $ hg push ../public

  [...]

  remote has heads on branch 'default' that are not known locally: 540ba8f317e6

  abort: push creates new remote head cbdfbd5a5db2!

  (pull and merge or see "hg help push" for details about pushing new heads)

Oops! Bob has won the race to push first to ``public``. So Alice needs

to integrate with Bob: let's pull his changeset(s) and see what the

branch heads are. ::

  $ hg pull ../public

  [...]

  added 1 changesets with 1 changes to 1 files (+1 heads)

  (run 'hg heads' to see heads, 'hg merge' to merge)

  $ hg log -G -q -r 'head()' --template '{rev}:{node|short}  ({author})\n'

  o  5:540ba8f317e6  (bob)

  |

  | @  4:cbdfbd5a5db2  (alice)

  |/

Since Alice and Bob are already using advanced technology in the form

of shared mutable history, we'll assume they are perfectly comfortable

with rebasing changesets. So Alice rebases her changeset on top of

Bob's and publishes the result::

  $ hg rebase -d 5

  $ hg push ../public

  [...]

  added 1 changesets with 1 changes to 1 files

  $ hg push ../review

  [...]

  added 1 changesets with 0 changes to 0 files

  updating bookmark bug15

The result, in both ``review`` and ``public`` repositories, is shown

in figure 8.

  [figure SG08: review shows v1 and v2 of alice's fix, then v1, v2, v3 of bob's feature, finally alice's fix rebased onto bob's. public just shows the final public version of each changeset]

** STOP HERE: WORK IN PROGRESS **