docs/sharing.rst
author Pierre-Yves David <pierre-yves.david@fb.com>
Fri, 11 Mar 2016 23:47:59 +0000
changeset 1621 05d15886aaeb
parent 1617 160968654581
child 2066 a35f6b1e4a41
permissions -rw-r--r--
test: explicitly disable rebaseskipobsolete in a couple of place (issue5135) We want to keep the old behavior for the sake of testing.
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
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
     7
.. contents::
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
     8
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
     9
Once you have mastered the art of mutable history in a single
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    10
repository (see the `user guide`_), you can move up to the next level:
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    11
*shared* mutable history. ``evolve`` lets you push and pull draft
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    12
changesets between repositories along with their obsolescence markers.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    13
This opens up a number of interesting possibilities.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    14
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    15
.. _`user guide`: user-guide.html
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    16
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    17
The simplest scenario is a single developer working across two
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    18
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
    19
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
    20
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
    21
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
    22
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
    23
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    24
Traditionally, your options are limited: either
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    25
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    26
  * (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
    27
    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
    28
  * 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
    29
    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
    30
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    31
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
    32
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
    33
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
    34
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
    35
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
    36
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
    37
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
    38
work.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    39
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    40
Using Mercurial with ``evolve`` to share mutable history solves these
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    41
problems. As with single-repository ``evolve``, you can commit
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    42
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
    43
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
    44
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
    45
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
    46
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    47
A less common scenario is multiple developers sharing mutable history,
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    48
typically for code review. We'll cover this scenario later. But first,
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    49
single-user sharing.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    50
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    51
Sharing with a single developer
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    52
-------------------------------
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    53
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    54
Publishing and non-publishing repositories
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    55
==========================================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    56
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    57
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
    58
*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
    59
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
    60
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
    61
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
    62
(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
    63
follows.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    64
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    65
Setting up
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
    66
==========
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    67
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    68
We'll work through an example with three local repositories, although
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    69
in the real world they'd most likely be on three different computers.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    70
First, the ``public`` repository is where tested, polished changesets
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    71
live, and it is where you synchronize with the rest of your team. ::
979
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
  $ hg init public
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    74
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    75
We'll need two clones where work gets done, ``test-repo`` and
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    76
``dev-repo``::
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    77
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    78
  $ hg clone public test-repo
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    79
  updating to branch default
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    80
  0 files updated, 0 files merged, 0 files removed, 0 files unresolved
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    81
  $ hg clone test-repo dev-repo
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    82
  updating to branch default
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    83
  0 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    84
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    85
``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
    86
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
    87
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
    88
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
    89
there, and push to ``public``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    90
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    91
The key to shared mutable history is to make the target repository, in
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    92
this case ``test-repo``, non-publishing. And, of course, we have to
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
    93
enable ``evolve`` in both ``test-repo`` and ``dev-repo``.
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    94
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    95
First, edit the configuration for ``test-repo``::
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
    96
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    97
  $ hg -R test-repo config --edit --local
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    98
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
    99
and add ::
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   100
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   101
  [phases]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   102
  publish = false
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   103
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   104
  [extensions]
1617
160968654581 url: update url to point to the latest hosting
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 1265
diff changeset
   105
  evolve = /path/to/evolve-main/hgext/evolve.py
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   106
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   107
Then edit the configuration for ``dev-repo``::
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   108
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   109
  $ hg -R dev-repo config --edit --local
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   110
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   111
and add ::
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   112
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   113
  [extensions]
1617
160968654581 url: update url to point to the latest hosting
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 1265
diff changeset
   114
  evolve = /path/to/evolve-main/hgext/evolve.py
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   115
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   116
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
   117
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
   118
each repository.
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
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
   121
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   122
  $ cd test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   123
  $ echo 'my new project' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   124
  $ hg add file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   125
  $ hg commit -m 'create new project'
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   126
  $ hg push
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   127
  [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   128
  added 1 changesets with 1 changes to 1 files
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   129
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   130
and pull that into the development repository::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   131
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   132
  $ cd ../dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   133
  $ hg pull -u
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   134
  [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   135
  added 1 changesets with 1 changes to 1 files
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   136
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   137
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   138
Example 1: Amend a shared changeset
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
   139
===================================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   140
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   141
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
   142
``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
   143
just as before.
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
.. _`user guide`: user-guide.html
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   146
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   147
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
   148
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
   149
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
   150
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
   151
draft (mutable) in ``test-repo``.
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
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
   154
testing. ::
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
  $ echo 'fix fix fix' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   157
  $ hg commit -m 'prelim change'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   158
  $ hg push ../test-repo
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
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
   161
in the same phases:
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   162
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   163
  [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
   164
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   165
(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
   166
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
   167
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
   168
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
   169
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
   170
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   171
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
   172
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   173
  $ cd ../test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   174
  $ hg update
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   175
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   176
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
   177
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
   178
you have a hook that updates for you).
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
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
   181
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
   182
(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
   183
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   184
  $ echo 'Fix fix fix.' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   185
  $ hg amend -m 'fix bug 37'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   186
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   187
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
   188
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
   189
(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
   190
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
   191
recent developments.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   192
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   193
  [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]
979
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
Let's resynchronize::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   196
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   197
  $ cd ../dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   198
  $ hg pull -u
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   199
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   200
  added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   201
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   202
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   203
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
   204
obsolescence marker for revision 1. However, it does *not* transfer
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   205
the temporary amend commit, because it is hidden. Push and pull
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   206
transfer obsolesence markers between repositories, but they do not
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   207
transfer hidden changesets.
979
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 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
   210
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   211
Because of this deliberately incomplete synchronization, revision
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   212
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
   213
*must* use changeset IDs.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   214
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   215
Example 2: Amend again, locally
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
   216
===============================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   217
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   218
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
   219
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
   220
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
   221
push to ``test-repo``::
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
  $ echo 'Fix, fix, and fix.' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   224
  $ hg amend
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   225
  $ hg push
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   226
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   227
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
   228
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
   229
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
   230
in ``dev-repo`` and pushing to ``test-repo``.
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
  [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
   233
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   234
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
   235
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   236
  $ cd ../test-repo
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   237
  $ hg update
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   238
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   239
1262
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
   240
This time, all the tests pass, so no further amending is required.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   241
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
   242
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   243
  $ hg push
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   244
  [...]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   245
  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
   246
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   247
Note that only one changeset—the final version, after two
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   248
amendments—was actually pushed. Again, Mercurial doesn't transfer
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   249
hidden changesets on push and pull.
979
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
.. _`concept guide`: concepts.html
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   252
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   253
So the picture in ``public`` is much simpler than in either
1262
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
   254
``dev-repo`` or ``test-repo``. Neither our missteps nor our amendments
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
   255
are publicly visible, just the final, beautifully polished changeset:
979
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
  [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
   258
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   259
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
   260
``test-repo`` to ``public``, the pushed changeset is in *public* phase
1263
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   261
in those two repositories. But ``dev-repo`` has been out-of-the-loop;
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   262
changeset de61 is still *draft* there. If we're not careful, we might
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   263
mutate history in ``dev-repo``, obsoleting a changeset that is already
1263
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   264
public. Let's avoid that situation for now by pushing up to
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   265
``dev-repo``::
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   266
1263
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   267
  $ hg push ../dev-repo
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   268
  pushing to ../dev-repo
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   269
  searching for changes
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   270
  no changes found
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   271
1263
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   272
Even though no *changesets* were pushed, Mercurial still pushed
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   273
obsolescence markers and phase changes to ``dev-repo``.
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   274
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   275
A final note: since this fix is now *public*, it is immutable. It's no
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   276
longer possible to amend it::
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   277
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   278
  $ hg amend -m 'fix bug 37'
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   279
  abort: cannot amend public changesets
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   280
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   281
This is, after all, the whole point of Mercurial's phases: to prevent
eb0a1d1d499b docs: sharing guide: clarify end-game of "Example 2"
Greg Ward <greg@gerg.ca>
parents: 1262
diff changeset
   282
rewriting history that has already been published.
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   283
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   284
Sharing with multiple developers: code review
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   285
---------------------------------------------
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   286
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   287
Now that you know how to share your own mutable history across
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   288
multiple computers, you might be wondering if it makes sense to share
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   289
mutable history with others. It does, but you have to be careful, stay
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   290
alert, and *communicate* with your peers.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   291
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   292
Code review is a good use case for sharing mutable history across
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   293
multiple developers: Alice commits a draft changeset, submits it for
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   294
review, and amends her changeset until her reviewer is satisfied.
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   295
Meanwhile, Bob is also committing draft changesets for review,
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   296
amending until his reviewer is satisfied. Once a particular changeset
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   297
passes review, the respective author (Alice or Bob) pushes it to the
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   298
public (publishing) repository.
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   299
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   300
Incidentally, the reviewers here can be anyone: maybe Bob and Alice
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   301
review each other's work; maybe the same third party reviews both; or
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   302
maybe they pick different experts to review their work on different
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   303
parts of a large codebase. Similarly, it doesn't matter if reviews are
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   304
conducted in person, by email, or by carrier pigeon. Code review is
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   305
outside of the scope of Mercurial, so all we're looking at here
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   306
is the mechanics of committing, amending, pushing, and pulling.
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   307
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   308
Setting up
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   309
==========
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   310
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   311
To demonstrate, let's start with the ``public`` repository as we left
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   312
it in the last example, with two immutable changesets (figure 5
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   313
above). We'll clone a ``review`` repository from it, and then Alice
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   314
and Bob will both clone from ``review``. ::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   315
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   316
  $ hg clone public review
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   317
  updating to branch default
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   318
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   319
  $ hg clone review alice
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   320
  updating to branch default
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   321
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   322
  $ hg clone review bob
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   323
  updating to branch default
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   324
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   325
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   326
We need to configure Alice's and Bob's working repositories to enable
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   327
``evolve``. First, edit Alice's configuration with ::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   328
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   329
  $ hg -R alice config --edit --local
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   330
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   331
and add ::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   332
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   333
  [extensions]
1617
160968654581 url: update url to point to the latest hosting
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 1265
diff changeset
   334
  evolve = /path/to/evolve-main/hgext/evolve.py
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   335
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   336
Then edit Bob's repository configuration::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   337
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   338
  $ hg -R bob config --edit --local
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   339
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   340
and add the same text.
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   341
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   342
Example 3: Alice commits and amends a draft fix
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   343
===============================================
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   344
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   345
We'll follow Alice working on a bug fix. We're going to use bookmarks to
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   346
make it easier to understand multiple branch heads in the ``review``
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   347
repository, so Alice starts off by creating a bookmark and committing
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   348
her first attempt at a fix::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   349
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   350
  $ hg bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   351
  $ echo 'fix' > file2
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   352
  $ hg commit -A -u alice -m 'fix bug 15 (v1)'
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   353
  adding file2
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   354
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   355
Note the unorthodox "(v1)" in the commit message. We're just using
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   356
that to make this tutorial easier to follow; it's not something we'd
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   357
recommend in real life.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   358
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   359
Of course Alice wouldn't commit unless her fix worked to her
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   360
satisfaction, so it must be time to solicit a code review. She does
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   361
this by pushing to the ``review`` repository::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   362
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   363
  $ hg push -B bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   364
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   365
  added 1 changesets with 1 changes to 1 files
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   366
  exporting bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   367
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   368
(The use of ``-B`` is important to ensure that we only push the
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   369
bookmarked head, and that the bookmark itself is pushed. See this
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   370
`guide to bookmarks`_, especially the `Sharing Bookmarks`_ section, if
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   371
you're not familiar with bookmarks.)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   372
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   373
.. _`guide to bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   374
.. _`Sharing Bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/#sharing-bookmarks
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   375
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   376
Some time passes, and Alice receives her code review. As a result,
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   377
Alice revises her fix and submits it for a second review::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   378
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   379
  $ echo 'Fix.' > file2
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   380
  $ hg amend -m 'fix bug 15 (v2)'
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   381
  $ hg push
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   382
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   383
  added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   384
  updating bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   385
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   386
Figure 6 shows the state of the ``review`` repository at this point.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   387
1262
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
   388
  [figure SG06: rev 2:fn1e is Alice's obsolete v1, rev 3:cbdf is her v2; both children of rev 1:de61]
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   389
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   390
After a busy morning of bug fixing, Alice stops for lunch. Let's see
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   391
what Bob has been up to.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   392
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   393
Example 4: Bob implements and publishes a new feature
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   394
=====================================================
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   395
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   396
Meanwhile, Bob has been working on a new feature. Like Alice, he'll
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   397
use a bookmark to track his work, and he'll push that bookmark to the
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   398
``review`` repository, so that reviewers know which changesets to
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   399
review. ::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   400
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   401
  $ cd ../bob
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   402
  $ echo 'stuff' > file1
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   403
  $ hg bookmark featureX
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   404
  $ hg commit -u bob -m 'implement feature X (v1)'          # rev 4:1636
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   405
  $ hg push -B featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   406
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   407
  added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   408
  exporting bookmark featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   409
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   410
When Bob receives his code review, he improves his implementation a
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   411
bit, amends, and submits the resulting changeset for review::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   412
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   413
  $ echo 'do stuff' > file1
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   414
  $ hg amend -m 'implement feature X (v2)'                  # rev 5:0eb7
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   415
  $ hg push
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   416
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   417
  added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   418
  updating bookmark featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   419
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   420
Unfortunately, that still doesn't pass muster. Bob's reviewer insists
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   421
on proper capitalization and punctuation. ::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   422
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   423
  $ echo 'Do stuff.' > file1
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   424
  $ hg amend -m 'implement feature X (v3)'                  # rev 6:540b
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   425
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   426
On the bright side, the second review said, "Go ahead and publish once
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   427
you fix that." So Bob immediately publishes his third attempt::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   428
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   429
  $ hg push ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   430
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   431
  added 1 changesets with 1 changes to 1 files
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   432
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   433
It's not enough just to update ``public``, though! Other people also
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   434
use the ``review`` repository, and right now it doesn't have Bob's
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   435
latest amendment ("v3", revision 6:540b), nor does it know that the
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   436
precursor of that changeset ("v2", revision 5:0eb7) is obsolete. Thus,
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   437
Bob pushes to ``review`` as well::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   438
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   439
  $ hg push ../review
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   440
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   441
  added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   442
  updating bookmark featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   443
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   444
Figure 7 shows the result of Bob's work in both ``review`` and
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   445
``public``.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   446
1262
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
   447
  [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]
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   448
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   449
Incidentally, it's important that Bob push to ``public`` *before*
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   450
``review``. If he pushed to ``review`` first, then revision 6:540b
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   451
would still be in *draft* phase in ``review``, but it would be
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   452
*public* in both Bob's local repository and the ``public`` repository.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   453
That could lead to confusion at some point, which is easily avoided by
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   454
pushing first to ``public``.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   455
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   456
Example 5: Alice integrates and publishes
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   457
=========================================
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   458
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   459
Finally, Alice gets back from lunch and sees that the carrier pigeon
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   460
with her second review has arrived (or maybe it's in her email inbox).
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   461
Alice's reviewer approved her amended changeset, so she pushes it to
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   462
``public``::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   463
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   464
  $ hg push ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   465
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   466
  remote has heads on branch 'default' that are not known locally: 540ba8f317e6
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   467
  abort: push creates new remote head cbdfbd5a5db2!
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   468
  (pull and merge or see "hg help push" for details about pushing new heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   469
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   470
Oops! Bob has won the race to push first to ``public``. So Alice needs
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   471
to integrate with Bob: let's pull his changeset(s) and see what the
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   472
branch heads are. ::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   473
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   474
  $ hg pull ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   475
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   476
  added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   477
  (run 'hg heads' to see heads, 'hg merge' to merge)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   478
  $ hg log -G -q -r 'head()' --template '{rev}:{node|short}  ({author})\n'
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   479
  o  5:540ba8f317e6  (bob)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   480
  |
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   481
  | @  4:cbdfbd5a5db2  (alice)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   482
  |/
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   483
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   484
We'll assume Alice and Bob are perfectly comfortable with rebasing
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   485
changesets. (After all, they're already using mutable history in the
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   486
form of ``amend``.) So Alice rebases her changeset on top of Bob's and
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
   487
publishes the result::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   488
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   489
  $ hg rebase -d 5
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   490
  $ hg push ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   491
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   492
  added 1 changesets with 1 changes to 1 files
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   493
  $ hg push ../review
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   494
  [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   495
  added 1 changesets with 0 changes to 0 files
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   496
  updating bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   497
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   498
The result, in both ``review`` and ``public`` repositories, is shown
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   499
in figure 8.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   500
1262
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
   501
  [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]
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   502
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   503
Getting into trouble with shared mutable history
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
   504
------------------------------------------------
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   505
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   506
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
   507
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
   508
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
   509
with a spoon?)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   510
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   511
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
   512
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
   513
non-obsolete changeset with obsolete ancestors is unstable.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   514
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   515
Two other types of trouble can happen: *divergent* and *bumped*
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   516
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
   517
especially mutable history shared by multiple developers.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   518
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   519
Setting up
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   520
==========
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   521
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   522
For these examples, we're going to use a slightly different workflow:
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   523
as before, Alice and Bob share a ``public`` repository. But this time
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   524
there is no ``review`` repository. Instead, Alice and Bob put on their
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   525
cowboy hats, throw good practice to the wind, and pull directly from
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   526
each other's working repositories.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   527
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   528
So we throw away everything except ``public`` and reclone::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   529
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   530
  $ rm -rf review alice bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   531
  $ hg clone public alice
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   532
  updating to branch default
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   533
  2 files updated, 0 files merged, 0 files removed, 0 files unresolved
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   534
  $ hg clone public bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   535
  updating to branch default
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   536
  2 files updated, 0 files merged, 0 files removed, 0 files unresolved
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   537
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   538
Once again we have to configure their repositories: enable ``evolve``
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   539
and (since Alice and Bob will be pulling directly from each other)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   540
make their repositories non-publishing. Edit Alice's configuration::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   541
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   542
  $ hg -R alice config --edit --local
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   543
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   544
and add ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   545
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   546
  [extensions]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   547
  rebase =
1617
160968654581 url: update url to point to the latest hosting
Pierre-Yves David <pierre-yves.david@fb.com>
parents: 1265
diff changeset
   548
  evolve = /path/to/evolve-main/hgext/evolve.py
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   549
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   550
  [phases]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   551
  publish = false
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   552
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   553
Then edit Bob's repository configuration::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   554
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   555
  $ hg -R bob config --edit --local
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   556
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   557
and add the same text.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   558
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   559
Example 6: Divergent changesets
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   560
===============================
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   561
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   562
When an obsolete changeset has two successors, those successors are
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   563
*divergent*. One way to get into such a situation is by failing to
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   564
communicate with your teammates. Let's see how that might happen.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   565
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   566
First, we'll have Bob commit a bug fix that could still be improved::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   567
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   568
  $ cd bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   569
  $ echo 'pretty good fix' >> file1
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   570
  $ hg commit -u bob -m 'fix bug 24 (v1)'                   # rev 4:2fe6
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   571
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   572
Since Alice and Bob are now in cowboy mode, Alice pulls Bob's draft
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   573
changeset and amends it herself. ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   574
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   575
  $ cd ../alice
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   576
  $ hg pull -u ../bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   577
  [...]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   578
  added 1 changesets with 1 changes to 1 files
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   579
  $ echo 'better fix (alice)' >> file1
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   580
  $ hg amend -u alice -m 'fix bug 24 (v2 by alice)'
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   581
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   582
But Bob has no idea that Alice just did this. (See how important good
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   583
communication is?) So he implements a better fix of his own::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   584
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   585
  $ cd ../bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   586
  $ echo 'better fix (bob)' >> file1
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   587
  $ hg amend -u bob -m 'fix bug 24 (v2 by bob)'             # rev 6:a360
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   588
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   589
At this point, the divergence exists, but only in theory: Bob's
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   590
original changeset, 4:2fe6, is obsolete and has two successors. But
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   591
those successors are in different repositories, so the trouble is not
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   592
visible to anyone yet. It will be as soon as Bob pulls from Alice's
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   593
repository (or vice-versa). ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   594
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   595
  $ hg pull ../alice
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   596
  [...]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   597
  added 1 changesets with 1 changes to 2 files (+1 heads)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   598
  (run 'hg heads' to see heads, 'hg merge' to merge)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   599
  2 new divergent changesets
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   600
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   601
Figure 9 shows the situation in Bob's repository.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   602
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   603
  [figure SG09: Bob's repo with 2 heads for the 2 divergent changesets, 6:a360 and 7:e3f9; wc is at 6:a360; both are successors of obsolete 4:2fe6, hence divergence]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   604
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   605
Now we need to get out of trouble. As usual, the answer is to evolve
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   606
history. ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   607
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   608
  $ HGMERGE=internal:other hg evolve
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   609
  merge:[6] fix bug 24 (v2 by bob)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   610
  with: [7] fix bug 24 (v2 by alice)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   611
  base: [4] fix bug 24 (v1)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   612
  0 files updated, 1 files merged, 0 files removed, 0 files unresolved
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   613
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   614
Figure 10 shows how Bob's repository looks now.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   615
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   616
  [figure SG10: only one visible head, 9:5ad6, successor to hidden 6:a360 and 7:e3f9]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   617
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   618
We carefully dodged a merge conflict by specifying a merge tool
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   619
(``internal:other``) that will take Alice's changes over Bob's. (You
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   620
might wonder why Bob wouldn't prefer his own changes by using
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   621
``internal:local``. He's avoiding a `bug`_ in ``evolve`` that occurs
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   622
when evolving divergent changesets using ``internal:local``.)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   623
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   624
.. _`bug`: https://bitbucket.org/marmoute/mutable-history/issue/48/
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   625
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   626
** STOP HERE: WORK IN PROGRESS **
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
   627
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   628
Bumped changesets: only one gets on the plane
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
   629
=============================================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   630
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   631
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
   632
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
   633
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
   634
*bumped*.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   635
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   636
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
   637
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
   638
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
   639
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
   640
Let's demonstrate one way this could happen.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   641
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   642
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
   643
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
   644
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
   645
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   646
  $ cd alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   647
  $ echo 'fix' > file2
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   648
  $ hg commit -A -m 'fix bug 15'
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   649
  adding file2
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   650
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   651
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
   652
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
   653
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   654
  $ cd ../bob
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   655
  $ hg pull -u ../alice
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   656
  [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   657
  added 1 changesets with 1 changes to 1 files
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   658
  1 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   659
  $ echo 'Fix.' > file2
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   660
  $ hg amend -A -m 'fix bug 15 (amended)'
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   661
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   662
(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
   663
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
   664
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
   665
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   666
  [figure SG06: Bob's repo with one amendment]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   667
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   668
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
   669
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
   670
publish. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   671
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   672
  $ cd ../alice
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   673
  $ hg push
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   674
  [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
   675
  added 1 changesets with 1 changes to 1 files
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   676
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   677
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
   678
(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
   679
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
   680
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
   681
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
   682
pulls from ``public``::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   683
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   684
  $ cd ../bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   685
  $ hg pull -q -u
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   686
  1 new bumped changesets
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   687
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   688
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
   689
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
   690
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
   691
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
   692
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
   693
it has been *bumped*.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   694
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   695
  [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
   696
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   697
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
   698
evolve it::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   699
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   700
  $ hg evolve --all
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   701
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   702
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
   703
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
   704
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
   705
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
   706
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
   707
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
   708
troubled changesets, thanks to ``evolve``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   709
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   710
  [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
   711
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   712
Conclusion
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   713
----------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   714
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   715
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
   716
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
   717
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
   718
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
   719
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
   720
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
   721
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
   722
being careful with sharp knives.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   723
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   724
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
   725
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
   726
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
   727
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
   728
between two chopping boards with different knives.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   729
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
   730
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
   731
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
   732
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
   733
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
   734
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
   735
practice a lot first before you rely on it!