evolve: docs/sharing.rst annotate

annotate docs/sharing.rst @ 1264:33ed6119a0be stable

docs (sharing): more scattered wording tweaks

author	Greg Ward <greg@gerg.ca>
date	Fri, 20 Jun 2014 08:19:04 -0400
parents	eb0a1d1d499b
children	14f91037d2f6

rev	line source
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]
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	105 evolve = /path/to/mutable-history/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]
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	114 evolve = /path/to/mutable-history/hgext/evolve.py
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]
56cc2eb5995a docs: add code review scenario to sharing guide Greg Ward <greg@gerg.ca> parents: 1260 diff changeset	334 evolve = /path/to/mutable-history/hgext/evolve.py
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
56cc2eb5995a docs: add code review scenario to sharing guide Greg Ward <greg@gerg.ca> parents: 1260 diff changeset	504 STOP HERE: WORK IN PROGRESS
56cc2eb5995a docs: add code review scenario to sharing guide Greg Ward <greg@gerg.ca> parents: 1260 diff changeset	505
56cc2eb5995a docs: add code review scenario to sharing guide Greg Ward <greg@gerg.ca> parents: 1260 diff changeset	506
56cc2eb5995a docs: add code review scenario to sharing guide Greg Ward <greg@gerg.ca> parents: 1260 diff changeset	507 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	508 ------------------------------------------------
979 c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	509
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	510 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	511 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	512 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	513 with a spoon?)
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	514
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	515 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	516 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	517 non-obsolete changeset with obsolete ancestors is unstable.)
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	518
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	519 Two other types of trouble can crop up: bumped and divergent
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	520 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	521 especially mutable history shared by multiple developers.
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	522
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	523 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	524 =============================================
979 c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	525
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	526 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	527 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	528 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	529 bumped.
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	530
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	531 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	532 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	533 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	534 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	535 Let's demonstrate one way this could happen.
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	536
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	537 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	538 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	539 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	540
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	541 $ cd alice
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	542 $ echo 'fix' > file2
1259 0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	543 $ 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	544 adding file2
979 c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	545
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	546 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	547 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	548
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	549 $ cd ../bob
1259 0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	550 $ hg pull -u ../alice
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	551 [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	552 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	553 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	554 $ echo 'Fix.' > file2
1259 0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	555 $ 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	556
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	557 (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	558 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	559 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	560
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	561 [figure SG06: Bob's repo with one amendment]
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	562
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	563 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	564 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	565 publish. ::
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	566
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	567 $ cd ../alice
1259 0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	568 $ hg push
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	569 [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	570 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	571
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	572 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	573 (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	574 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	575 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	576 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	577 pulls from ``public``::
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	578
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	579 $ cd ../bob
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	580 $ hg pull -q -u
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	581 1 new bumped changesets
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	582
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	583 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	584 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	585 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	586 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	587 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	588 it has been bumped.
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	589
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	590 [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	591
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	592 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	593 evolve it::
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	594
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	595 $ hg evolve --all
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	596
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	597 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	598 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	599 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	600 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	601 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	602 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	603 troubled changesets, thanks to ``evolve``.
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	604
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	605 [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	606
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	607 Divergent changesets
1260 e8016d1011b5 docs: add a bit more hierarchy to the sharing guide Greg Ward <greg@gerg.ca> parents: 1259 diff changeset	608 ====================
979 c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	609
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	610 In addition to unstable and bumped, there is a third kind of
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	611 troubled changeset: divergent. When an obsolete changeset has two
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	612 successors, those successors are divergent.
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	613
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	614 To illustrate, let's start Alice and Bob at the same
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	615 point—specifically, the point where Alice's repository currently
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	616 stands. Bob's repository is a bit of a mess, so we'll throw it away
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	617 and start him off with a copy of Alice's repository::
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	618
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	619 $ cd ..
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	620 $ rm -rf bob
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	621 $ cp -rp alice bob
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	622
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	623 Now we'll have Bob commit a bug fix that could still be improved::
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	624
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	625 $ cd bob
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	626 $ echo 'pretty good fix' >> file1
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	627 $ hg commit -u bob -m 'fix bug 24 (v1)'
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	628
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	629 This time, Alice meddles with her colleague's work (still a bad
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	630 idea)::
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	631
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	632 $ cd ../alice
1259 0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	633 $ hg pull -u ../bob
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	634 [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review Greg Ward <greg@gerg.ca> parents: 1186 diff changeset	635 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	636 $ echo 'better (alice)' >> file1
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	637 $ hg amend -u alice -m 'fix bug 24 (v2 by alice)'
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	638
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	639 Here's where things change from the "bumped" scenario above: this
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	640 time, the original author (Bob) decides to amend his changeset too. ::
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	641
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	642 $ cd ../bob
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	643 $ echo 'better (bob)' >> file1
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	644 $ hg amend -u bob -m 'fix bug 24 (v2 by bob)'
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	645
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	646 At this point, the divergence exists, but only in theory: Bob's
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	647 original changeset, 3:fe81, is obsolete and has two successors. But
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	648 those successors are in different repositories, so the trouble is not
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	649 visible to anyone yet. It will be as soon as one of our players pulls
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	650 from the other's repository. Let's make Bob the victim again::
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	651
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	652 $ hg pull -q -u ../alice
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	653 not updating: not a linear update
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	654 (merge or update --check to force update)
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	655 2 new divergent changesets
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	656
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	657 The “not a linear update” is our first hint that something is wrong,
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	658 but of course “2 new divergent changesets” is the real problem. Figure
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	659 9 shows both problems.
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	660
1262 eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless) Greg Ward <greg@gerg.ca> parents: 1261 diff changeset	661 [figure SG09: Bob's repo with 2 heads for the 2 divergent changesets, 5:fc16 and 6:694f; wc is at 5:fc16, hence update refused; both are successors of obsolete 3:fe81, hence divergence]
979 c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	662
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	663 Now we need to get out of trouble. Unfortunately, a `bug`_ in
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	664 ``evolve`` means that the usual answer (run ``hg evolve --all``) does
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	665 not work. Bob has to figure out the solution on his own: in this case,
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	666 merge. To avoid distractions, we'll set ``HGMERGE`` to make Mercurial
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	667 resolve any conflicts in favour of Bob. ::
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	668
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	669 $ HGMERGE=internal:local hg merge
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	670 $ hg commit -m merge
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 .. _`bug`: https://bitbucket.org/marmoute/mutable-history/issue/48/
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	673
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	674 This is approximately what ``hg evolve`` would do in this
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	675 circumstance, if not for that bug. One annoying difference is that
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	676 Mercurial thinks the two divergent changesets are still divergent,
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	677 which you can see with a simple revset query::
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	678
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	679 $ hg log -q -r 'divergent()'
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	680 5:fc16901f4d7a
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	681 6:694fd0f6b503
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	682
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	683 (That annoyance should go away when the bug is fixed.)
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	684
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	685 Conclusion
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	686 ----------
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 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	689 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	690 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	691 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	692 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	693 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	694 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	695 being careful with sharp knives.
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 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	698 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	699 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	700 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	701 between two chopping boards with different knives.
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	702
c7b2ccd99dab docs: add guide to sharing mutable history Greg Ward <greg@gerg.ca> parents: diff changeset	703 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	704 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	705 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	706 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	707 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	708 practice a lot first before you rely on it!

Mercurial > evolve

annotate docs/sharing.rst @ 1264:33ed6119a0be stable