comparison docs/sharing.rst @ 1259:0daf56a2032d stable

docs: update sharing guide based (mostly) on marmoute's review

- don't claim certain scenarios are more/less common, just
  simple/advanced
- mention code review as a multiple-developer scenario (not described
  in detail yet!)
- suggest "hg config --edit --local" instead of "cat >> .hg/hgrc"
- use -q less often (and show resulting output)
- edit some section headers to be consistent with user guide
  (example numbers; "amend" instead of "amending")

(These are just the small changes; big changes are yet to come.)

1258:8873aedbd83d

------------------------------
Evolve: Shared Mutable History
------------------------------

Once you have mastered the art of mutable history in a single
repository, you might want to 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.

The most common scenario is a single developer working across two
computers. Say you're working on code that must be tested on a remote
test server, probably in a rack somewhere, only accessible by SSH, and
running an “enterprise-grade” (out-of-date) OS. But you probably
prefer to write code locally: everything is setup the way you like it,
and you can use your preferred editor, IDE, merge/diff tools, etc.

whenever the code is demonstrably better, even if all the tests aren't
passing yet—just ``hg amend`` when they are. And you can transfer
those half-baked changesets between repositories to try things out on
your test server before anything is carved in stone.

A less common scenario is multiple developers sharing mutable history.
(This is in fact how Mercurial itself is developed.) We'll cover this
scenario later. But first, single-user sharing.

Publishing and non-publishing repositories
------------------------------------------

The key to shared mutable history is to keep your changesets in

Setting things up
-----------------

We'll work 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 push/pull changesets to/from the rest of your team. ::

  $ hg init public

We'll need two clones where work gets done::

  $ hg clone -q public test-repo
  $ hg clone -q test-repo dev-repo

``dev-repo`` is your local machine, with GUI merge tools and IDEs and
everything configured just the way you like it. ``test-repo`` is the
test server in a rack somewhere behind SSH. So for the most part,
we'll develop in ``dev-repo``, push to ``test-repo``, test and polish
there, and push to ``public``.

The key to making this whole thing work is to make ``test-repo``
non-publishing::

  $ cat >> test-repo/.hg/hgrc <<EOF
  [phases]
  publish = false
  EOF

We also have to configure ``evolve`` in both ``test-repo`` and
``dev-repo``, so that we can amend and evolve in both of them. ::

  $ cat >> test-repo/.hg/hgrc <<EOF
  [extensions]
  evolve = /path/to/mutable-history/hgext/evolve.py
  EOF
  $ cat >> dev-repo/.hg/hgrc <<EOF
  [extensions]
  evolve = /path/to/mutable-history/hgext/evolve.py
  EOF

Keep in mind that in real life, these repositories would probably be
on separate computers, so you'd have to login to each one to configure
each repository.

  $ cd test-repo
  $ echo 'my new project' > file1
  $ hg add file1
  $ hg commit -m 'create new project'
  $ hg push -q

and pull that into the development repository::

  $ cd ../dev-repo
  $ hg pull -u

Amending a shared changeset
---------------------------

Everything you learned in the `user guide`_ applies to work done in
``dev-repo``. You can commit, amend, uncommit, evolve, and so forth
just as before.

Because of this deliberately incomplete synchronization, revision
numbers in ``test-repo`` and ``dev-repo`` are no longer consistent. We
*must* use changeset IDs.

Amend again, locally
--------------------

This process can repeat. Perhaps you figure out a more elegant fix to
the bug, and want to mutate history so nobody ever knows you had a
less-than-perfect idea. We'll implement it locally in ``dev-repo`` and
push to ``test-repo``::

  [figure SG04: each repo has one temporary amend commit, but they're different in each one]

Let's hop over to ``test-repo`` to test the more elegant fix::

  $ cd ../test-repo
  $ hg update -q

This time, all the tests pass, so no further amendment is required.
This bug fix is finished, so we push it to the public repository::

  $ hg push

To demonstrate, let's start with the ``public`` repository as we left
it in the last example, with two immutable changesets (figure 5
above). Two developers, Alice and Bob, start working from this point::

  $ hg clone -q public alice
  $ hg clone -q public bob

We need to configure Alice's and Bob's working repositories similar to
``test-repo``, i.e. make them non-publishing and enable ``evolve``::

  $ cat >> alice/.hg/hgrc <<EOF

know if this bug fix is good enough to push to the public repository,
but it's good enough for Alice to commit. ::

  $ cd alice
  $ echo 'fix' > file2
  $ hg commit -q -A -m 'fix bug 15'

Now Bob has a bad idea: he decides to pull whatever Alice is working
on and tweak her bug fix to his taste::

  $ cd ../bob
  $ hg pull -q -u ../alice
  $ echo 'Fix.' > file2
  $ hg amend -q -A -m 'fix bug 15 (amended)'

(Note the lack of communication between Alice and Bob. Failing to
communicate with your colleagues is a good way to get into trouble.
Nevertheless, ``evolve`` can usually sort things out, as we will see.)

After some testing, Alice realizes her bug fix is just fine as it is:
no need for further polishing and amending, this changeset is ready to
publish. ::

  $ cd ../alice
  $ hg push  -q

This introduces a contradiction: in Bob's repository, changeset 2:e011
(his copy of Alice's fix) is obsolete, since Bob amended it. But in
Alice's repository (and ``public``), that changeset is public: it is
immutable, carved in stone for all eternity. No changeset can be both

This time, Alice meddles with her colleague's work (still a bad
idea)::

  $ cd ../alice
  $ hg pull -q -u ../bob
  $ echo 'better (alice)' >> file1
  $ hg amend -u alice -m 'fix bug 24 (v2 by alice)'

Here's where things change from the "bumped" scenario above: this
time, the original author (Bob) decides to amend his changeset too. ::

1259:0daf56a2032d

------------------------------
Evolve: Shared Mutable History
------------------------------

Once you have mastered the art of mutable history in a single
repository (see the `user guide`_), you might want to 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.

.. _`user guide`: user-guide.html

The simplest scenario is a single developer working across two
computers. Say you're working on code that must be tested on a remote
test server, probably in a rack somewhere, only accessible by SSH, and
running an “enterprise-grade” (out-of-date) OS. But you probably
prefer to write code locally: everything is setup the way you like it,
and you can use your preferred editor, IDE, merge/diff tools, etc.

whenever the code is demonstrably better, even if all the tests aren't
passing yet—just ``hg amend`` when they are. And you can transfer
those half-baked changesets between repositories to try things out on
your test server before anything is carved in stone.

A less common scenario is multiple developers sharing mutable history,
typically for code review. We'll cover this scenario later. But first,
single-user sharing.

Publishing and non-publishing repositories
------------------------------------------

The key to shared mutable history is to keep your changesets in

Setting things up
-----------------

We'll work 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 changesets with the rest of your team.
::

  $ hg init public

We'll need two clones where work gets done::

  $ hg clone public test-repo
  updating to branch default
  0 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg clone test-repo dev-repo
  updating to branch default
  0 files updated, 0 files merged, 0 files removed, 0 files unresolved

``dev-repo`` is your local machine, with GUI merge tools and IDEs and
everything configured just the way you like it. ``test-repo`` is the
test server in a rack somewhere behind SSH. So for the most part,
we'll develop in ``dev-repo``, push to ``test-repo``, test and polish
there, and push to ``public``.

The key to shared mutable history is to make the target repository,
``test-repo`` in this case, non-publishing. And, of course, we have to enable ``evolve`` in both ``test-repo`` and ``dev-repo``.

First, edit the configuration for ``test-repo``::

  $ hg -R test-repo config --edit --local

and add ::

  [phases]
  publish = false

  [extensions]
  evolve = /path/to/mutable-history/hgext/evolve.py

Then edit the configuration for ``dev-repo``::

  $ hg -R dev-repo config --edit --local

and add ::

  [extensions]
  evolve = /path/to/mutable-history/hgext/evolve.py

Keep in mind that in real life, these repositories would probably be
on separate computers, so you'd have to login to each one to configure
each repository.

  $ cd test-repo
  $ echo 'my new project' > file1
  $ hg add file1
  $ hg commit -m 'create new project'
  $ hg push
  [...]
  added 1 changesets with 1 changes to 1 files

and pull that into the development repository::

  $ cd ../dev-repo
  $ hg pull -u
  [...]
  added 1 changesets with 1 changes to 1 files
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

Example 1: Amend a shared changeset
-----------------------------------

Everything you learned in the `user guide`_ applies to work done in
``dev-repo``. You can commit, amend, uncommit, evolve, and so forth
just as before.

Because of this deliberately incomplete synchronization, revision
numbers in ``test-repo`` and ``dev-repo`` are no longer consistent. We
*must* use changeset IDs.

Example 2: Amend again, locally
-------------------------------

This process can repeat. Perhaps you figure out a more elegant fix to
the bug, and want to mutate history so nobody ever knows you had a
less-than-perfect idea. We'll implement it locally in ``dev-repo`` and
push to ``test-repo``::

  [figure SG04: each repo has one temporary amend commit, but they're different in each one]

Let's hop over to ``test-repo`` to test the more elegant fix::

  $ cd ../test-repo
  $ hg update
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved

This time, all the tests pass, so no further amendment is required.
This bug fix is finished, so we push it to the public repository::

  $ hg push

To demonstrate, let's start with the ``public`` repository as we left
it in the last example, with two immutable changesets (figure 5
above). Two developers, Alice and Bob, start working from this point::

  $ hg clone public alice
  updating to branch default
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ hg clone public 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``::

  $ cat >> alice/.hg/hgrc <<EOF

know if this bug fix is good enough to push to the public repository,
but it's good enough for Alice to commit. ::

  $ cd alice
  $ echo 'fix' > file2
  $ hg commit -A -m 'fix bug 15'
  adding file2

Now Bob has a bad idea: he decides to pull whatever Alice is working
on and tweak her bug fix to his taste::

  $ cd ../bob
  $ hg pull -u ../alice
  [...]
  added 1 changesets with 1 changes to 1 files
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
  $ echo 'Fix.' > file2
  $ hg amend -A -m 'fix bug 15 (amended)'

(Note the lack of communication between Alice and Bob. Failing to
communicate with your colleagues is a good way to get into trouble.
Nevertheless, ``evolve`` can usually sort things out, as we will see.)

After some testing, Alice realizes her bug fix is just fine as it is:
no need for further polishing and amending, this changeset is ready to
publish. ::

  $ cd ../alice
  $ hg push
  [...]
  added 1 changesets with 1 changes to 1 files

This introduces a contradiction: in Bob's repository, changeset 2:e011
(his copy of Alice's fix) is obsolete, since Bob amended it. But in
Alice's repository (and ``public``), that changeset is public: it is
immutable, carved in stone for all eternity. No changeset can be both

This time, Alice meddles with her colleague's work (still a bad
idea)::

  $ cd ../alice
  $ hg pull -u ../bob
  [...]
  added 1 changesets with 1 changes to 1 files
  $ echo 'better (alice)' >> file1
  $ hg amend -u alice -m 'fix bug 24 (v2 by alice)'

Here's where things change from the "bumped" scenario above: this
time, the original author (Bob) decides to amend his changeset too. ::