Mercurial > evolve

annotate docs/sharing.rst @ 1260:e8016d1011b5 stable

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
docs: add a bit more hierarchy to the sharing guide
author Greg Ward <greg@gerg.ca>
date Mon, 09 Jun 2014 08:18:43 -0400
parents 0daf56a2032d
children 56cc2eb5995a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
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
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
10 repository (see the `user guide`_), you might want to move up to the
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
11 next level: *shared* mutable history. ``evolve`` lets you push and
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
12 pull draft changesets between repositories along with their
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
13 obsolescence markers. This opens up a number of interesting
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
14 possibilities.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
15
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
16 .. _`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
17
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
18 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
19 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
20 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
21 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
22 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
23 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
24
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
25 Traditionally, your options are limited: either
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
26
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
27 * (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
28 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
29 * 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
30 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
31
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
32 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
33 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
34 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
35 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
36 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
37 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
38 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
39 work.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
40
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
41 Using Mercurial with ``evolve`` to share mutable history solves all of
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
42 these problems. As with single-repository ``evolve``, you can commit
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
43 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
44 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
45 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
46 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
47
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
48 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
49 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
50 single-user sharing.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
51
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
52 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
53 -------------------------------
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
54
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
55 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
56 ==========================================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
57
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
58 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
59 *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
60 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
61 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
62 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
63 (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
64 follows.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
65
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
66 Setting up
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
67 ==========
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
68
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
69 We'll work an example with three local repositories, although in the
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
70 real world they'd most likely be on three different computers. First,
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
71 the ``public`` repository is where tested, polished changesets live,
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
72 and it is where you synchronize changesets with the rest of your team.
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
73 ::
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
74
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
75 $ hg init public
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
76
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
77 We'll need two clones where work gets done::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
78
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
79 $ 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
80 updating to branch default
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
81 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
82 $ 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
83 updating to branch default
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
84 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
85
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
86 ``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
87 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
88 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
89 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
90 there, and push to ``public``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
91
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
92 The key to shared mutable history is to make the target repository,
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
93 ``test-repo`` in this case, non-publishing. And, of course, we have to enable ``evolve`` in both ``test-repo`` and ``dev-repo``.
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
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
193 [figure SG02: rev 0:0dc9 public, rev 1:f649, 2:2a03 obsolete, rev 3:60ff draft -- but dev-repo same as in SG01]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
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
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
199
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
200 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
201 obsolescence marker for revision 1. However, it does *not* transfer
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
202 the temporary amend commit, because it is obsolete. Push and pull
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
203 transfer obsolesence markers between repositories, but they do not
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
204 normally transfer obsolete changesets.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
205
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
206 [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
207
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
208 Because of this deliberately incomplete synchronization, revision
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
209 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
210 *must* use changeset IDs.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
211
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
212 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
213 ===============================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
214
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
215 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
216 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
217 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
218 push to ``test-repo``::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
219
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
220 $ echo 'Fix, fix, and fix.' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
221 $ hg amend
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
222 $ hg push
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
223
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
224 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
225 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
226 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
227 in ``dev-repo`` and pushing to ``test-repo``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
228
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
229 [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
230
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
231 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
232
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
233 $ cd ../test-repo
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
234 $ hg update
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
235 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
236
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
237 This time, all the tests pass, so no further amendment is required.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
238 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
239
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
240 $ hg push
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
241 [...]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
242 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
243
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
244 Note that only one changeset—the final version, after two
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
245 amendments—was actually pushed. Again, Mercurial normally doesn't
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
246 transfer obsolete changesets on push and pull. (Specifically, it
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
247 doesn't transfer *hidden* changesets: roughly speaking, obsolete
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
248 changesets with no non-obsolete descendants. If you're curious, see
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
249 the `concept guide`_ for the precise definition of hidden.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
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
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
254 ``dev-repo`` or ``test-repo``. None of our missteps or amendments are
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
255 visible publicly, just the final, beautifully polished changeset:
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
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
261 in those two repositories. But ``dev-repo`` knows nothing of this:
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
262 that changeset is still *draft* there. If we're not careful, we might
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
263 mutate history in ``dev-repo``, obsoleting a changeset that is already
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
264 public. Let's avoid that situation for now by pulling from
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
265 ``test-repo`` down to ``dev-repo``::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
266
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
267 $ cd ../dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
268 $ hg pull -u
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
269
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
270 Sharing with multiple developers
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
271 --------------------------------
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
272
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
273 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
274 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
275 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
276 with a spoon?)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
277
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
278 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
279 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
280 non-obsolete changeset with obsolete ancestors is unstable.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
281
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
282 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
283 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
284 especially mutable history shared by multiple developers.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
285
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
286 Setting up
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
287 ==========
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
288
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
289 To demonstrate, let's start with the ``public`` repository as we left
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
290 it in the last example, with two immutable changesets (figure 5
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
291 above). Two developers, Alice and Bob, start working from this point::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
292
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
293 $ hg clone public alice
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
294 updating to branch default
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
295 1 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
296 $ hg clone public bob
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
297 updating to branch default
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
298 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
299
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
300 We need to configure Alice's and Bob's working repositories similar to
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
301 ``test-repo``, i.e. make them non-publishing and enable ``evolve``::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
302
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
303 $ cat >> alice/.hg/hgrc <<EOF
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
304 [phases]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
305 publish = false
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
306 [extensions]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
307 evolve = /path/to/mutable-history/hgext/evolve.py
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
308 EOF
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
309 $ cp alice/.hg/hgrc bob/.hg/hgrc
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
310
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
311 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
312 =============================================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
313
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
314 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
315 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
316 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
317 *bumped*.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
318
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
319 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
320 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
321 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
322 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
323 Let's demonstrate one way this could happen.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
324
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
325 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
326 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
327 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
328
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
329 $ cd alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
330 $ echo 'fix' > file2
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
331 $ 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
332 adding file2
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
333
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
334 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
335 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
336
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
337 $ cd ../bob
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
338 $ hg pull -u ../alice
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
339 [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
340 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
341 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
342 $ echo 'Fix.' > file2
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
343 $ 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
344
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
345 (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
346 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
347 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
348
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
349 [figure SG06: Bob's repo with one amendment]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
350
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
351 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
352 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
353 publish. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
354
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
355 $ cd ../alice
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
356 $ hg push
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
357 [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
358 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
359
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
360 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
361 (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
362 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
363 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
364 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
365 pulls from ``public``::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
366
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
367 $ cd ../bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
368 $ hg pull -q -u
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
369 1 new bumped changesets
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
370
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
371 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
372 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
373 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
374 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
375 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
376 it has been *bumped*.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
377
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
378 [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
379
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
380 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
381 evolve it::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
382
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
383 $ hg evolve --all
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
384
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
385 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
386 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
387 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
388 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
389 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
390 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
391 troubled changesets, thanks to ``evolve``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
392
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
393 [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
394
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
395 Divergent changesets
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
396 ====================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
397
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
398 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
399 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
400 successors, those successors are divergent.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
401
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
402 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
403 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
404 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
405 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
406
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
407 $ cd ..
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
408 $ rm -rf bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
409 $ cp -rp alice bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
410
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
411 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
412
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
413 $ cd bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
414 $ echo 'pretty good fix' >> file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
415 $ 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
416
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
417 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
418 idea)::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
419
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
420 $ cd ../alice
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
421 $ hg pull -u ../bob
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
422 [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
423 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
424 $ echo 'better (alice)' >> file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
425 $ 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
426
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
427 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
428 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
429
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
430 $ cd ../bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
431 $ echo 'better (bob)' >> file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
432 $ 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
433
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
434 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
435 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
436 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
437 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
438 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
439
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
440 $ hg pull -q -u ../alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
441 not updating: not a linear update
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
442 (merge or update --check to force update)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
443 2 new divergent changesets
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
444
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
445 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
446 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
447 9 shows both problems.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
448
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
449 [figure SG09: bob's repo with 2 heads for the 2 divergent changesets, 5:fc16 and 6:694f; wc is at 5:fc16, hence update refused; both are successors of obsolete 3:fe81, hence divergence]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
450
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
451 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
452 ``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
453 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
454 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
455 resolve any conflicts in favour of Bob. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
456
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
457 $ HGMERGE=internal:local hg merge
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
458 $ hg commit -m merge
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
459
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
460 .. _`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
461
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
462 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
463 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
464 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
465 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
466
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
467 $ hg log -q -r 'divergent()'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
468 5:fc16901f4d7a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
469 6:694fd0f6b503
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
470
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
471 (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
472
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
473 Conclusion
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
474 ----------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
475
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
476 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
477 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
478 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
479 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
480 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
481 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
482 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
483 being careful with sharp knives.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
484
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
485 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
486 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
487 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
488 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
489 between two chopping boards with different knives.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
490
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
491 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
492 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
493 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
494 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
495 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
496 practice a lot first before you rely on it!