docs/sharing.rst
author Pierre-Yves David <pierre-yves.david@fb.com>
Tue, 11 Nov 2014 11:26:57 +0000
branchstable
changeset 1155 3ad45ed74313
parent 979 c7b2ccd99dab
child 1186 0b66826f081c
permissions -rw-r--r--
merge back with compat branch
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     1
.. Copyright © 2014 Greg Ward <greg@gerg.ca>
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     2
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     3
------------------------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     4
Evolve: Shared Mutable History
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     5
------------------------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     6
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     7
Once you have mastered the art of mutable history in a single
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     8
repository, you might want to move up to the next level: *shared*
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     9
mutable history. ``evolve`` lets you push and pull draft changesets
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    10
between repositories along with their obsolescence markers. This opens
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    11
up a number of interesting possibilities.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    12
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    13
The most common scenario is a single developer working across two
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    14
computers. Say you're working on code that must be tested on a remote
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    15
test server, probably in a rack somewhere, only accessible by SSH, and
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    16
running an “enterprise-grade” (out-of-date) OS. But you probably
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    17
prefer to write code locally: everything is setup the way you like it,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    18
and you can use your preferred editor, IDE, merge/diff tools, etc.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    19
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    20
Traditionally, your options are limited: either
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    21
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    22
  * (ab)use your source control system by committing half-working code
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    23
    in order to get it onto the remote test server, or
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    24
  * go behind source control's back by using ``rsync`` (or similar) to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    25
    transfer your code back-and-forth until it is ready to commit
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    26
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    27
The former is less bad with distributed version control systems like
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    28
Mercurial, but it's still far from ideal. (One important version
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    29
control “best practice” is that every commit should make things just a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    30
little bit better, i.e. you should never commit code that is worse
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    31
than what came before.) The latter, avoiding version control entirely,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    32
means that you're walking a tightrope without a safety net. One
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    33
accidental ``rsync`` in the wrong direction could destroy hours of
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    34
work.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    35
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    36
Using Mercurial with ``evolve`` to share mutable history solves all of
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    37
these problems. As with single-repository ``evolve``, you can commit
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    38
whenever the code is demonstrably better, even if all the tests aren't
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    39
passing yet—just ``hg amend`` when they are. And you can transfer
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    40
those half-baked changesets between repositories to try things out on
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    41
your test server before anything is carved in stone.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    42
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    43
A less common scenario is multiple developers sharing mutable history.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    44
(This is in fact how Mercurial itself is developed.) We'll cover this
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    45
scenario later. But first, single-user sharing.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    46
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    47
Publishing and non-publishing repositories
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    48
------------------------------------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    49
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    50
The key to shared mutable history is to keep your changesets in
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    51
*draft* phase as you pass them around. Recall that by default, ``hg
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    52
push`` promotes changesets from *draft* to *public*, and public
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    53
changesets are immutable. You can change this behaviour by
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    54
reconfiguring the *target* repository so that it is non-publishing.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    55
(Short version: set ``phases.publish`` to ``false``. Long version
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    56
follows.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    57
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    58
Setting things up
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    59
-----------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    60
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    61
We'll work an example with three local repositories, although in the
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    62
real world they'd most likely be on three different computers. First,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    63
the public repository is where tested, polished changesets live, and
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    64
it is where you push/pull changesets to/from the rest of your team. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    65
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    66
  $ hg init public
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    67
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    68
We'll need two clones where work gets done::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    69
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    70
  $ hg clone -q public test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    71
  $ hg clone -q test-repo dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    72
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    73
``dev-repo`` is your local machine, with GUI merge tools and IDEs and
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    74
everything configured just the way you like it. ``test-repo`` is the
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    75
test server in a rack somewhere behind SSH. So for the most part,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    76
we'll develop in ``dev-repo``, push to ``test-repo``, test and polish
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    77
there, and push to ``public``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    78
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    79
The key to making this whole thing work is to make ``test-repo``
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    80
non-publishing::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    81
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    82
  $ cat >> test-repo/.hg/hgrc <<EOF
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    83
  [phases]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    84
  publish = false
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    85
  EOF
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    86
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    87
We also have to configure ``evolve`` in both ``test-repo`` and
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    88
``dev-repo``, so that we can amend and evolve in both of them. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    89
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    90
  $ cat >> test-repo/.hg/hgrc <<EOF
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    91
  [extensions]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    92
  rebase =
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    93
  evolve = /path/to/mutable-history/hgext/evolve.py
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    94
  EOF
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    95
  $ cat >> dev-repo/.hg/hgrc <<EOF
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    96
  [extensions]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    97
  rebase =
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    98
  evolve = /path/to/mutable-history/hgext/evolve.py
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    99
  EOF
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   100
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   101
Keep in mind that in real life, these repositories would probably be
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   102
on separate computers, so you'd have to login to each one to configure
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   103
each repository.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   104
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   105
To start things off, let's make one public, immutable changeset::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   106
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   107
  $ cd test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   108
  $ echo 'my new project' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   109
  $ hg add file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   110
  $ hg commit -m 'create new project'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   111
  $ hg push -q
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   112
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   113
and pull that into the development repository::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   114
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   115
  $ cd ../dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   116
  $ hg pull -u
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   117
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   118
Amending a shared changeset
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   119
---------------------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   120
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   121
Everything you learned in the `user guide`_ applies to work done in
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   122
``dev-repo``. You can commit, amend, uncommit, evolve, and so forth
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   123
just as before.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   124
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   125
.. _`user guide`: user-guide.html
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   126
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   127
Things get different when you push changesets to ``test-repo``. Or
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   128
rather, things stay the same, which *is* different: because we
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   129
configured ``test-repo`` to be non-publishing, draft changesets stay
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   130
draft when we push them to ``test-repo``. Importantly, they're also
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   131
draft (mutable) in ``test-repo``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   132
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   133
Let's commit a preliminary change and push it to ``test-repo`` for
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   134
testing. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   135
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   136
  $ echo 'fix fix fix' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   137
  $ hg commit -m 'prelim change'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   138
  $ hg push ../test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   139
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   140
At this point, ``dev-repo`` and ``test-repo`` have the same changesets
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   141
in the same phases:
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   142
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   143
  [figure SG01: rev 0:0dc9 public, rev 1:f649 draft, same on both repos]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   144
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   145
(You may notice a change in notation from the user guide: now
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   146
changesets are labelled with their revision number and the first four
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   147
digits of the 40-digit hexadecimal changeset ID. Mercurial revision
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   148
numbers are never stable when working across repositories, especially
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   149
when obsolescence is involved. We'll see why shortly.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   150
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   151
Now let's switch to ``test-repo`` to test our change::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   152
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   153
  $ cd ../test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   154
  $ hg update
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   155
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   156
Don't forget to ``hg update``! Pushing only adds changesets to a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   157
remote repository; it does not update the working directory (unless
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   158
you have a hook that updates for you).
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   159
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   160
Now let's imagine the tests failed because we didn't use proper
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   161
punctuation and capitalization (oops). Let's amend our preliminary fix
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   162
(and fix the lame commit message while we're at it)::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   163
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   164
  $ echo 'Fix fix fix.' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   165
  $ hg amend -m 'fix bug 37'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   166
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   167
Now we're in a funny intermediate state (figure 2): revision 1:f649 is
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   168
obsolete in ``test-repo``, having been replaced by revision 3:60ff
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   169
(revision 2:2a03 is another one of those temporary amend commits that
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   170
we saw in the user guide)—but ``dev-repo`` knows nothing of these
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   171
recent developments.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   172
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   173
  [figure SG02: rev 0:0dc9 public, rev 1:f649, 2:2a03 obsolete, rev 3:60ff draft -- but dev-repo same as in SG01]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   174
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   175
Let's resynchronize::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   176
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   177
  $ cd ../dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   178
  $ hg pull -u
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   179
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   180
As seen in figure 3, this transfers the new changeset *and* the
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   181
obsolescence marker for revision 1. However, it does *not* transfer
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   182
the temporary amend commit, because it is obsolete. Push and pull
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   183
transfer obsolesence markers between repositories, but they do not
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   184
normally transfer obsolete changesets.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   185
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   186
  [figure SG03: dev-repo grows new rev 2:60ff, marks 1:f649 obsolete]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   187
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   188
Because of this deliberately incomplete synchronization, revision
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   189
numbers in ``test-repo`` and ``dev-repo`` are no longer consistent. We
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   190
*must* use changeset IDs.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   191
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   192
Amend again, locally
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   193
--------------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   194
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   195
This process can repeat. Perhaps you figure out a more elegant fix to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   196
the bug, and want to mutate history so nobody ever knows you had a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   197
less-than-perfect idea. We'll implement it locally in ``dev-repo`` and
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   198
push to ``test-repo``::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   199
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   200
  $ echo 'Fix, fix, and fix.' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   201
  $ hg amend
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   202
  $ hg push
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   203
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   204
This time around, the temporary amend commit is in ``dev-repo``, and
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   205
it is not transferred to ``test-repo``—the same as before, just in the
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   206
opposite direction. Figure 4 shows the two repositories after amending
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   207
in ``dev-repo`` and pushing to ``test-repo``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   208
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   209
  [figure SG04: each repo has one temporary amend commit, but they're different in each one]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   210
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   211
Let's hop over to ``test-repo`` to test the more elegant fix::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   212
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   213
  $ cd ../test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   214
  $ hg update -q
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   215
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   216
This time, all the tests pass, so no further amendment is required.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   217
This bug fix is finished, so we push it to the public repository::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   218
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   219
  $ hg push
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   220
  [...]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   221
  added 1 changesets with 1 changes to 1 files
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   222
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   223
Note that only one changeset—the final version, after two
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   224
amendments—was actually pushed. Again, Mercurial normally doesn't
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   225
transfer obsolete changesets on push and pull. (Specifically, it
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   226
doesn't transfer *hidden* changesets: roughly speaking, obsolete
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   227
changesets with no non-obsolete descendants. If you're curious, see
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   228
the `concept guide`_ for the precise definition of hidden.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   229
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   230
.. _`concept guide`: concepts.html
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   231
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   232
So the picture in ``public`` is much simpler than in either
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   233
``dev-repo`` or ``test-repo``. None of our missteps or amendments are
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   234
visible publicly, just the final, beautifully polished changeset:
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   235
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   236
  [figure SG05: public repo with rev 0:0dc9, 1:de61, both public]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   237
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   238
There is one important step left to do. Because we pushed from
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   239
``test-repo`` to ``public``, the pushed changeset is in *public* phase
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   240
in those two repositories. But ``dev-repo`` knows nothing of this:
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   241
that changeset is still *draft* there. If we're not careful, we might
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   242
mutate history in ``dev-repo``, obsoleting a changeset that is already
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   243
public. Let's avoid that situation for now by pulling from
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   244
``test-repo`` down to ``dev-repo``::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   245
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   246
  $ cd ../dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   247
  $ hg pull -u
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   248
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   249
Getting into trouble
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   250
--------------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   251
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   252
Mercurial with ``evolve`` is a powerful tool, and using powerful tools
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   253
can have consequences. (You can cut yourself badly with a sharp knife,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   254
but every competent chef keeps several around. Ever try to chop onions
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   255
with a spoon?)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   256
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   257
In the user guide, we saw examples of *unstable* changesets, which are
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   258
the most common type of troubled changeset. (Recall that a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   259
non-obsolete changeset with obsolete ancestors is unstable.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   260
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   261
Two other types of trouble can crop up: *bumped* and *divergent*
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   262
changesets. Both are more likely with shared mutable history,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   263
especially mutable history shared by multiple developers.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   264
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   265
To demonstrate, let's start with the ``public`` repository as we left
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   266
it in the last example, with two immutable changesets (figure 5
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   267
above). Two developers, Alice and Bob, start working from this point::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   268
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   269
  $ hg clone -q public alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   270
  $ hg clone -q public bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   271
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   272
We need to configure Alice's and Bob's working repositories similar to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   273
``test-repo``, i.e. make them non-publishing and enable ``evolve``::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   274
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   275
  $ cat >> alice/.hg/hgrc <<EOF
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   276
  [phases]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   277
  publish = false
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   278
  [extensions]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   279
  rebase =
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   280
  evolve = /path/to/mutable-history/hgext/evolve.py
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   281
  EOF
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   282
  $ cp alice/.hg/hgrc bob/.hg/hgrc
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   283
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   284
Bumped changesets: only one gets on the plane
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   285
---------------------------------------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   286
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   287
If two people show up at the airport with tickets for the same seat on
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   288
the same plane, only one of them gets on the plane. The would-be
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   289
traveller left behind in the airport terminal is said to have been
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   290
*bumped*.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   291
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   292
Similarly, if Alice and Bob are collaborating on some mutable
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   293
changesets, it's possible to get into a situation where an otherwise
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   294
worthwhile changeset cannot be pushed to the public repository; it is
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   295
bumped by an alternative changeset that happened to get there first.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   296
Let's demonstrate one way this could happen.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   297
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   298
It starts with Alice committing a bug fix. Right now, we don't yet
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   299
know if this bug fix is good enough to push to the public repository,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   300
but it's good enough for Alice to commit. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   301
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   302
  $ cd alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   303
  $ echo 'fix' > file2
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   304
  $ hg commit -q -A -m 'fix bug 15'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   305
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   306
Now Bob has a bad idea: he decides to pull whatever Alice is working
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   307
on and tweak her bug fix to his taste::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   308
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   309
  $ cd ../bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   310
  $ hg pull -q -u ../alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   311
  $ echo 'Fix.' > file2
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   312
  $ hg amend -q -A -m 'fix bug 15 (amended)'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   313
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   314
(Note the lack of communication between Alice and Bob. Failing to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   315
communicate with your colleagues is a good way to get into trouble.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   316
Nevertheless, ``evolve`` can usually sort things out, as we will see.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   317
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   318
  [figure SG06: Bob's repo with one amendment]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   319
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   320
After some testing, Alice realizes her bug fix is just fine as it is:
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   321
no need for further polishing and amending, this changeset is ready to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   322
publish. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   323
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   324
  $ cd ../alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   325
  $ hg push  -q
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   326
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   327
This introduces a contradiction: in Bob's repository, changeset 2:e011
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   328
(his copy of Alice's fix) is obsolete, since Bob amended it. But in
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   329
Alice's repository (and ``public``), that changeset is public: it is
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   330
immutable, carved in stone for all eternity. No changeset can be both
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   331
obsolete and public, so Bob is in for a surprise the next time he
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   332
pulls from ``public``::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   333
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   334
  $ cd ../bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   335
  $ hg pull -q -u
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   336
  1 new bumped changesets
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   337
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   338
Figure 7 shows what just happened to Bob's repository: changeset
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   339
2:e011 is now public, so it can't be obsolete. When that changeset was
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   340
obsolete, it made perfect sense for it to have a successor, namely
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   341
Bob's amendment of Alice's fix (changeset 4:fe88). But it's illogical
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   342
for a public changeset to have a successor, so 4:fe88 is in trouble:
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   343
it has been *bumped*.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   344
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   345
  [figure SG07: 2:e011 now public not obsolete, 4:fe88 now bumped]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   346
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   347
As usual when there's trouble in your repository, the solution is to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   348
evolve it::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   349
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   350
  $ hg evolve --all
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   351
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   352
Figure 8 illustrate's Bob's repository after evolving away the bumped
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   353
changeset. Ignoring the obsolete changesets, Bob now has a nice,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   354
clean, simple history. His amendment of Alice's bug fix lives on, as
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   355
changeset 5:227d—albeit with a software-generated commit message. (Bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   356
should probably amend that changeset to improve the commit message.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   357
But the important thing is that his repository no longer has any
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   358
troubled changesets, thanks to ``evolve``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   359
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   360
  [figure SG08: 5:227d is new, formerly bumped changeset 4:fe88 now hidden]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   361
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   362
Divergent changesets
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   363
--------------------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   364
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   365
In addition to *unstable* and *bumped*, there is a third kind of
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   366
troubled changeset: *divergent*. When an obsolete changeset has two
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   367
successors, those successors are divergent.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   368
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   369
To illustrate, let's start Alice and Bob at the same
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   370
point—specifically, the point where Alice's repository currently
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   371
stands. Bob's repository is a bit of a mess, so we'll throw it away
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   372
and start him off with a copy of Alice's repository::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   373
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   374
  $ cd ..
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   375
  $ rm -rf bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   376
  $ cp -rp alice bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   377
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   378
Now we'll have Bob commit a bug fix that could still be improved::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   379
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   380
  $ cd bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   381
  $ echo 'pretty good fix' >> file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   382
  $ hg commit -u bob -m 'fix bug 24 (v1)'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   383
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   384
This time, Alice meddles with her colleague's work (still a bad
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   385
idea)::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   386
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   387
  $ cd ../alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   388
  $ hg pull -q -u ../bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   389
  $ echo 'better (alice)' >> file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   390
  $ hg amend -u alice -m 'fix bug 24 (v2 by alice)'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   391
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   392
Here's where things change from the "bumped" scenario above: this
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   393
time, the original author (Bob) decides to amend his changeset too. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   394
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   395
  $ cd ../bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   396
  $ echo 'better (bob)' >> file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   397
  $ hg amend -u bob -m 'fix bug 24 (v2 by bob)'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   398
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   399
At this point, the divergence exists, but only in theory: Bob's
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   400
original changeset, 3:fe81, is obsolete and has two successors. But
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   401
those successors are in different repositories, so the trouble is not
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   402
visible to anyone yet. It will be as soon as one of our players pulls
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   403
from the other's repository. Let's make Bob the victim again::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   404
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   405
  $ hg pull -q -u ../alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   406
  not updating: not a linear update
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   407
  (merge or update --check to force update)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   408
  2 new divergent changesets
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   409
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   410
The “not a linear update” is our first hint that something is wrong,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   411
but of course “2 new divergent changesets” is the real problem. Figure
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   412
9 shows both problems.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   413
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   414
  [figure SG09: bob's repo with 2 heads for the 2 divergent changesets, 5:fc16 and 6:694f; wc is at 5:fc16, hence update refused; both are successors of obsolete 3:fe81, hence divergence]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   415
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   416
Now we need to get out of trouble. Unfortunately, a `bug`_ in
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   417
``evolve`` means that the usual answer (run ``hg evolve --all``) does
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   418
not work. Bob has to figure out the solution on his own: in this case,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   419
merge. To avoid distractions, we'll set ``HGMERGE`` to make Mercurial
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   420
resolve any conflicts in favour of Bob. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   421
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   422
  $ HGMERGE=internal:local hg merge
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   423
  $ hg commit -m merge
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   424
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   425
.. _`bug`: https://bitbucket.org/marmoute/mutable-history/issue/48/
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   426
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   427
This is approximately what ``hg evolve`` would do in this
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   428
circumstance, if not for that bug. One annoying difference is that
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   429
Mercurial thinks the two divergent changesets are still divergent,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   430
which you can see with a simple revset query::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   431
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   432
  $ hg log -q -r 'divergent()'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   433
  5:fc16901f4d7a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   434
  6:694fd0f6b503
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   435
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   436
(That annoyance should go away when the bug is fixed.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   437
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   438
Conclusion
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   439
----------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   440
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   441
Mutable history is a powerful tool. Like a sharp knife, an experienced
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   442
user can do wonderful things with it, much more wonderful than with a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   443
dull knife (never mind a rusty spoon). At the same time, an
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   444
inattentive or careless user can do harm to himself or others.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   445
Mercurial with ``evolve`` goes to great lengths to limit the harm you
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   446
can do by trying to handle all possible types of “troubled”
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   447
changesets. But having a first-aid kit nearby does not excuse you from
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   448
being careful with sharp knives.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   449
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   450
Mutable history shared across multiple repositories by a single
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   451
developer is a natural extension of this model. Once you are used to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   452
using a single sharp knife on its own, it's pretty straightforward to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   453
chop onions and mushrooms using the same knife, or to alternate
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   454
between two chopping boards with different knives.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   455
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   456
Mutable history shared by multiple developers is a scary place to go.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   457
Imagine a professional kitchen full of expert chefs tossing their
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   458
favourite knives back and forth, with the occasional axe or chainsaw
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   459
thrown in to spice things up. If you're confident that you *and your
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   460
colleagues* can do it without losing a limb, go for it. But be sure to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   461
practice a lot first before you rely on it!