Mercurial > evolve

annotate docs/sharing.rst @ 2932:0afd41ac31d2

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
sharing: edit pass
author Ryan McElroy <rmcelroy@fb.com>
date Wed, 30 Aug 2017 17:32:32 +0200
parents b0b8cc3064b0
children
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
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,
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
48 typically for code review. We'll cover this scenario later. First, we
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
49 will cover 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
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
58 *draft* phase as you pass them around. Recall that by default,
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
59 ``hg push`` promotes changesets from *draft* to *public*, and public
979
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
2863
3e3a276c9e91 doc: reword "target repository" to "remote repository"
Philippe Pepiot <phil@philpep.org>
parents: 2862
diff changeset
61 reconfiguring the *remote* repository so that it is non-publishing.
979
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
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
93 enable the ``evolve`` extension 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]
2865
b0b8cc3064b0 doc: let mercurial find where evolve is installed
Philippe Pepiot <phil@philpep.org>
parents: 2863
diff changeset
105 evolve =
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]
2865
b0b8cc3064b0 doc: let mercurial find where evolve is installed
Philippe Pepiot <phil@philpep.org>
parents: 2863
diff changeset
114 evolve =
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
115
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
116 Keep in mind that in real life, these repositories would probably be
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
117 on separate computers, so you'd have to login to each one to configure
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
118 each repository.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
119
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
120 To start things off, let's make one public, immutable changeset::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
121
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
122 $ cd test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
123 $ echo 'my new project' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
124 $ hg add file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
125 $ hg commit -m 'create new project'
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
126 $ hg push
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
127 [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
128 added 1 changesets with 1 changes to 1 files
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
129
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
130 and pull that into the development repository::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
131
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
132 $ cd ../dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
133 $ hg pull -u
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
134 [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
135 added 1 changesets with 1 changes to 1 files
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
136 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
137
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
138 Example 1: Amend a shared changeset
1260
e8016d1011b5 docs: add a bit more hierarchy to the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1259
diff changeset
139 ===================================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
140
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
141 Everything you learned in the `user guide`_ applies to work done in
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
142 ``dev-repo``. You can commit, amend, uncommit, evolve, and so forth
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
143 just as before.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
144
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
145 .. _`user guide`: user-guide.html
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
146
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
147 Things get different when you push changesets to ``test-repo``. Or
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
148 rather, things stay the same, which *is* different: because we
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
149 configured ``test-repo`` to be non-publishing, draft changesets stay
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
150 draft when we push them to ``test-repo``. Importantly, they're also
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
151 draft (mutable) in ``test-repo``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
152
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
153 Let's commit a preliminary change and push it to ``test-repo`` for
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
154 testing. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
155
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
156 $ echo 'fix fix fix' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
157 $ hg commit -m 'prelim change'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
158 $ hg push ../test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
159
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
160 At this point, ``dev-repo`` and ``test-repo`` have the same changesets
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
161 in the same phases:
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
162
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
163 [figure SG01: rev 0:0dc9 public, rev 1:f649 draft, same on both repos]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
164
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
165 (You may notice a change in notation from the user guide: now
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
166 changesets are labelled with their revision number and the first four
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
167 digits of the 40-digit hexadecimal changeset ID. Mercurial revision
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
168 numbers are never stable when working across repositories, especially
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
169 when obsolescence is involved. We'll see why shortly.)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
170
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
171 Now let's switch to ``test-repo`` to test our change::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
172
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
173 $ cd ../test-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
174 $ hg update
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
175
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
176 Don't forget to ``hg update``! Pushing only adds changesets to a
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
177 remote repository; it does not update the working directory (unless
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
178 you have a hook that updates for you).
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
179
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
180 Now let's imagine the tests failed because we didn't use proper
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
181 punctuation and capitalization (oops). Let's amend our preliminary fix
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
182 (and fix the lame commit message while we're at it)::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
183
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
184 $ echo 'Fix fix fix.' > file1
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
185 $ hg amend -m 'fix bug 37'
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
186
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
187 Now we're in a funny intermediate state (figure 2): revision 1:f649 is
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
188 obsolete in ``test-repo``, having been replaced by revision 3:60ff
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
189 (revision 2:2a03 is another one of those temporary amend commits that
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
190 we saw in the user guide)—but ``dev-repo`` knows nothing of these
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
191 recent developments.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
192
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
193 [figure SG02: test-repo has rev 0:0dc9 public, rev 1:f649, 2:2a03 obsolete, rev 3:60ff draft; dev-repo same as in SG01]
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
194
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
195 Let's resynchronize::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
196
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
197 $ cd ../dev-repo
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
198 $ hg pull -u
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
199 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
200 added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
201 1 files updated, 0 files merged, 0 files removed, 0 files unresolved
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
202
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
203 As seen in figure 3, this transfers the new changeset *and* the
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
204 obsolescence marker for revision 1. However, it does *not* transfer
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
205 the temporary amend commit, because it is hidden. Push and pull
2862
07ce6c063c61 doc: typo fixes
Philippe Pepiot <phil@philpep.org>
parents: 2066
diff changeset
206 transfer obsolescence 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
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
254 ``dev-repo`` or ``test-repo``. Neither of our missteps nor our amendments
1262
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]
2865
b0b8cc3064b0 doc: let mercurial find where evolve is installed
Philippe Pepiot <phil@philpep.org>
parents: 2863
diff changeset
334 evolve =
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
335
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
336 Then edit Bob's repository configuration::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
337
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
338 $ hg -R bob config --edit --local
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
339
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
340 and add the same text.
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
341
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
342 Example 3: Alice commits and amends a draft fix
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
343 ===============================================
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
344
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
345 We'll follow Alice working on a bug fix. We're going to use bookmarks to
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
346 make it easier to understand multiple branch heads in the ``review``
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
347 repository, so Alice starts off by creating a bookmark and committing
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
348 her first attempt at a fix::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
349
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
350 $ hg bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
351 $ echo 'fix' > file2
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
352 $ hg commit -A -u alice -m 'fix bug 15 (v1)'
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
353 adding file2
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
354
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
355 Note the unorthodox "(v1)" in the commit message. We're just using
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
356 that to make this tutorial easier to follow; it's not something we'd
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
357 recommend in real life.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
358
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
359 Of course Alice wouldn't commit unless her fix worked to her
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
360 satisfaction, so it must be time to solicit a code review. She does
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
361 this by pushing to the ``review`` repository::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
362
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
363 $ hg push -B bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
364 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
365 added 1 changesets with 1 changes to 1 files
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
366 exporting bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
367
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
368 (The use of ``-B`` is important to ensure that we only push the
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
369 bookmarked head, and that the bookmark itself is pushed. See this
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
370 `guide to bookmarks`_, especially the `Sharing Bookmarks`_ section, if
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
371 you're not familiar with bookmarks.)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
372
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
373 .. _`guide to bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
374 .. _`Sharing Bookmarks`: http://mercurial.aragost.com/kick-start/en/bookmarks/#sharing-bookmarks
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
375
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
376 Some time passes, and Alice receives her code review. As a result,
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
377 Alice revises her fix and submits it for a second review::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
378
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
379 $ echo 'Fix.' > file2
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
380 $ hg amend -m 'fix bug 15 (v2)'
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
381 $ hg push
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
382 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
383 added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
384 updating bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
385
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
386 Figure 6 shows the state of the ``review`` repository at this point.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
387
1262
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
388 [figure SG06: rev 2:fn1e is Alice's obsolete v1, rev 3:cbdf is her v2; both children of rev 1:de61]
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
389
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
390 After a busy morning of bug fixing, Alice stops for lunch. Let's see
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
391 what Bob has been up to.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
392
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
393 Example 4: Bob implements and publishes a new feature
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
394 =====================================================
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
395
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
396 Meanwhile, Bob has been working on a new feature. Like Alice, he'll
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
397 use a bookmark to track his work, and he'll push that bookmark to the
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
398 ``review`` repository, so that reviewers know which changesets to
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
399 review. ::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
400
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
401 $ cd ../bob
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
402 $ echo 'stuff' > file1
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
403 $ hg bookmark featureX
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
404 $ hg commit -u bob -m 'implement feature X (v1)' # rev 4:1636
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
405 $ hg push -B featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
406 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
407 added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
408 exporting bookmark featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
409
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
410 When Bob receives his code review, he improves his implementation a
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
411 bit, amends, and submits the resulting changeset for review::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
412
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
413 $ echo 'do stuff' > file1
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
414 $ hg amend -m 'implement feature X (v2)' # rev 5:0eb7
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
415 $ hg push
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
416 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
417 added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
418 updating bookmark featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
419
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
420 Unfortunately, that still doesn't pass muster. Bob's reviewer insists
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
421 on proper capitalization and punctuation. ::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
422
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
423 $ echo 'Do stuff.' > file1
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
424 $ hg amend -m 'implement feature X (v3)' # rev 6:540b
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
425
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
426 On the bright side, the second review said, "Go ahead and publish once
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
427 you fix that." So Bob immediately publishes his third attempt::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
428
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
429 $ hg push ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
430 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
431 added 1 changesets with 1 changes to 1 files
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
432
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
433 It's not enough just to update ``public``, though! Other people also
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
434 use the ``review`` repository, and right now it doesn't have Bob's
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
435 latest amendment ("v3", revision 6:540b), nor does it know that the
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
436 precursor of that changeset ("v2", revision 5:0eb7) is obsolete. Thus,
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
437 Bob pushes to ``review`` as well::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
438
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
439 $ hg push ../review
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
440 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
441 added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
442 updating bookmark featureX
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
443
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
444 Figure 7 shows the result of Bob's work in both ``review`` and
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
445 ``public``.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
446
1262
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
447 [figure SG07: review includes Alice's draft work on bug 15, as well as Bob's v1, v2, and v3 changes for feature X: v1 and v2 obsolete, v3 public. public contains only the final, public implementation of feature X]
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
448
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
449 Incidentally, it's important that Bob push to ``public`` *before*
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
450 ``review``. If he pushed to ``review`` first, then revision 6:540b
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
451 would still be in *draft* phase in ``review``, but it would be
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
452 *public* in both Bob's local repository and the ``public`` repository.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
453 That could lead to confusion at some point, which is easily avoided by
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
454 pushing first to ``public``.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
455
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
456 Example 5: Alice integrates and publishes
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
457 =========================================
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
458
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
459 Finally, Alice gets back from lunch and sees that the carrier pigeon
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
460 with her second review has arrived (or maybe it's in her email inbox).
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
461 Alice's reviewer approved her amended changeset, so she pushes it to
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
462 ``public``::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
463
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
464 $ hg push ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
465 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
466 remote has heads on branch 'default' that are not known locally: 540ba8f317e6
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
467 abort: push creates new remote head cbdfbd5a5db2!
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
468 (pull and merge or see "hg help push" for details about pushing new heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
469
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
470 Oops! Bob has won the race to push first to ``public``. So Alice needs
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
471 to integrate with Bob: let's pull his changeset(s) and see what the
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
472 branch heads are. ::
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
473
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
474 $ hg pull ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
475 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
476 added 1 changesets with 1 changes to 1 files (+1 heads)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
477 (run 'hg heads' to see heads, 'hg merge' to merge)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
478 $ hg log -G -q -r 'head()' --template '{rev}:{node|short} ({author})\n'
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
479 o 5:540ba8f317e6 (bob)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
480 |
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
481 | @ 4:cbdfbd5a5db2 (alice)
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
482 |/
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
483
1264
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
484 We'll assume Alice and Bob are perfectly comfortable with rebasing
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
485 changesets. (After all, they're already using mutable history in the
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
486 form of ``amend``.) So Alice rebases her changeset on top of Bob's and
33ed6119a0be docs (sharing): more scattered wording tweaks
Greg Ward <greg@gerg.ca>
parents: 1263
diff changeset
487 publishes the result::
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
488
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
489 $ hg rebase -d 5
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
490 $ hg push ../public
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
491 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
492 added 1 changesets with 1 changes to 1 files
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
493 $ hg push ../review
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
494 [...]
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
495 added 1 changesets with 0 changes to 0 files
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
496 updating bookmark bug15
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
497
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
498 The result, in both ``review`` and ``public`` repositories, is shown
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
499 in figure 8.
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
500
1262
eff1acc2511c docs: minor tweaks to sharing guide (suggested by timeless)
Greg Ward <greg@gerg.ca>
parents: 1261
diff changeset
501 [figure SG08: review shows v1 and v2 of Alice's fix, then v1, v2, v3 of Bob's feature, finally Alice's fix rebased onto Bob's. public just shows the final public version of each changeset]
1261
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
502
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
503 Getting into trouble with shared mutable history
56cc2eb5995a docs: add code review scenario to sharing guide
Greg Ward <greg@gerg.ca>
parents: 1260
diff changeset
504 ------------------------------------------------
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
505
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
506 Mercurial with ``evolve`` is a powerful tool, and using powerful tools
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
507 can have consequences. (You can cut yourself badly with a sharp knife,
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
508 but every competent chef keeps several around. Ever try to chop onions
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
509 with a spoon?)
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
510
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
511 In the user guide, we saw examples of *unstbale* changesets, which are
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
512 the most common type of troubled changeset. (Recall that a
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
513 non-obsolete changeset with obsolete ancestors is an orphan.)
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
514
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
515 Two other types of troubles can happen: *divergent* and
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
516 *bumped* changesets. Both are more likely with shared mutable
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
517 history, especially mutable history shared by multiple developers.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
518
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
519 Setting up
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
520 ==========
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
521
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
522 For these examples, we're going to use a slightly different workflow:
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
523 as before, Alice and Bob share a ``public`` repository. But this time
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
524 there is no ``review`` repository. Instead, Alice and Bob put on their
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
525 cowboy hats, throw good practice to the wind, and pull directly from
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
526 each other's working repositories.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
527
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
528 So we throw away everything except ``public`` and reclone::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
529
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
530 $ rm -rf review alice bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
531 $ hg clone public alice
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
532 updating to branch default
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
533 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
534 $ hg clone public bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
535 updating to branch default
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
536 2 files updated, 0 files merged, 0 files removed, 0 files unresolved
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
537
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
538 Once again we have to configure their repositories: enable ``evolve``
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
539 and (since Alice and Bob will be pulling directly from each other)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
540 make their repositories non-publishing. Edit Alice's configuration::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
541
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
542 $ hg -R alice config --edit --local
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
543
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
544 and add ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
545
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
546 [extensions]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
547 rebase =
2865
b0b8cc3064b0 doc: let mercurial find where evolve is installed
Philippe Pepiot <phil@philpep.org>
parents: 2863
diff changeset
548 evolve =
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
549
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
550 [phases]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
551 publish = false
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
552
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
553 Then edit Bob's repository configuration::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
554
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
555 $ hg -R bob config --edit --local
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
556
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
557 and add the same text.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
558
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
559 Example 6: Divergent changesets
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
560 ===============================
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
561
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
562 When an obsolete changeset has two successors, those successors are
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
563 *divergent*. One way to get into such a situation is by failing
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
564 to communicate with your teammates. Let's see how that might happen.
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
565
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
566 First, we'll have Bob commit a bug fix that could still be improved::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
567
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
568 $ cd bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
569 $ echo 'pretty good fix' >> file1
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
570 $ hg commit -u bob -m 'fix bug 24 (v1)' # rev 4:2fe6
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
571
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
572 Since Alice and Bob are now in cowboy mode, Alice pulls Bob's draft
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
573 changeset and amends it herself. ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
574
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
575 $ cd ../alice
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
576 $ hg pull -u ../bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
577 [...]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
578 added 1 changesets with 1 changes to 1 files
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
579 $ echo 'better fix (alice)' >> file1
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
580 $ hg amend -u alice -m 'fix bug 24 (v2 by alice)'
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
581
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
582 But Bob has no idea that Alice just did this. (See how important good
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
583 communication is?) So he implements a better fix of his own::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
584
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
585 $ cd ../bob
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
586 $ echo 'better fix (bob)' >> file1
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
587 $ hg amend -u bob -m 'fix bug 24 (v2 by bob)' # rev 6:a360
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
588
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
589 At this point, the divergence exists, but only in theory: Bob's
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
590 original changeset, 4:2fe6, is obsolete and has two successors. But
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
591 those successors are in different repositories, so the trouble is not
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
592 visible to anyone yet. It will be as soon as Bob pulls from Alice's
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
593 repository (or vice-versa). ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
594
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
595 $ hg pull ../alice
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
596 [...]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
597 added 1 changesets with 1 changes to 2 files (+1 heads)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
598 (run 'hg heads' to see heads, 'hg merge' to merge)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
599 2 new divergent changesets
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
600
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
601 Figure 9 shows the situation in Bob's repository.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
602
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
603 [figure SG09: Bob's repo with 2 heads for the 2 divergent changesets, 6:a360 and 7:e3f9; wc is at 6:a360; both are successors of obsolete 4:2fe6, hence divergence]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
604
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
605 Now we need to get out of trouble. As usual, the answer is to evolve
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
606 history. ::
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
607
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
608 $ HGMERGE=internal:other hg evolve
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
609 merge:[6] fix bug 24 (v2 by bob)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
610 with: [7] fix bug 24 (v2 by alice)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
611 base: [4] fix bug 24 (v1)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
612 0 files updated, 1 files merged, 0 files removed, 0 files unresolved
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
613
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
614 Figure 10 shows how Bob's repository looks now.
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
615
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
616 [figure SG10: only one visible head, 9:5ad6, successor to hidden 6:a360 and 7:e3f9]
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
617
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
618 We carefully dodged a merge conflict by specifying a merge tool
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
619 (``internal:other``) that will take Alice's changes over Bob's. (You
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
620 might wonder why Bob wouldn't prefer his own changes by using
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
621 ``internal:local``. He's avoiding a `bug`_ in ``evolve`` that occurs
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
622 when evolving divergent changesets using ``internal:local``.)
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
623
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
624 # XXX this link does not work
1265
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
625 .. _`bug`: https://bitbucket.org/marmoute/mutable-history/issue/48/
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
626
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
627 ** STOP HERE: WORK IN PROGRESS **
14f91037d2f6 docs: revive the explanation of divergent changesets in the sharing guide
Greg Ward <greg@gerg.ca>
parents: 1264
diff changeset
628
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
629 Phase-divergence: when a rewritten changeset is made public
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
630 ===========================================================
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
631
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
632 If Alice and Bob are collaborating on some mutable
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
633 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
634 worthwhile changeset cannot be pushed to the public repository; it is
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
635 *phase-divergent* with another changeset that was made public first.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
636 Let's demonstrate one way this could happen.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
637
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
638 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
639 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
640 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
641
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
642 $ cd alice
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
643 $ echo 'fix' > file2
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
644 $ 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
645 adding file2
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
646
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
647 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
648 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
649
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
650 $ cd ../bob
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
651 $ hg pull -u ../alice
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
652 [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
653 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
654 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
655 $ echo 'Fix.' > file2
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
656 $ 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
657
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
658 (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
659 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
660 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
661
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
662 [figure SG06: Bob's repo with one amendment]
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
663
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
664 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
665 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
666 publish. ::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
667
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
668 $ cd ../alice
1259
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
669 $ hg push
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
670 [...]
0daf56a2032d docs: update sharing guide based (mostly) on marmoute's review
Greg Ward <greg@gerg.ca>
parents: 1186
diff changeset
671 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
672
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
673 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
674 (his copy of Alice's fix) is obsolete, since Bob amended it. But in
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
675 Alice's repository (and the ``public`` repository), that changeset is
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
676 public: it is immutable, carved in stone for all eternity. No changeset
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
677 can be both obsolete and public, so Bob is in for a surprise the next
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
678 time he pulls from ``public``::
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
679
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
680 $ cd ../bob
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
681 $ hg pull -q -u
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
682 1 new phase-divergent changesets
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
683
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
684 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
685 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
686 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
687 Bob's amendment of Alice's fix (changeset 4:fe88). But it's illogical
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
688 for a public changeset to have a successor, so 4:fe88 is troubled:
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
689 it has become *bumped*.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
690
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
691 [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
692
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
693 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
694 evolve it::
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
695
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
696 $ hg evolve --all
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
697
2862
07ce6c063c61 doc: typo fixes
Philippe Pepiot <phil@philpep.org>
parents: 2066
diff changeset
698 Figure 8 illustrates Bob's repository after evolving away the bumped
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
699 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
700 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
701 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
702 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
703 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
704 troubled changesets, thanks to ``evolve``.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
705
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
706 [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
707
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
708 Conclusion
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
709 ----------
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
710
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
711 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
712 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
713 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
714 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
715 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
716 can do by trying to handle all possible types of “troubled”
2932
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
717 changesets. Nevertheless, having a first-aid kit nearby does not mean
0afd41ac31d2 sharing: edit pass
Ryan McElroy <rmcelroy@fb.com>
parents: 2865
diff changeset
718 you should stop being careful with sharp knives.
979
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
719
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
720 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
721 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
722 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
723 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
724 between two chopping boards with different knives.
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
725
c7b2ccd99dab docs: add guide to sharing mutable history
Greg Ward <greg@gerg.ca>
parents:
diff changeset
726 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
727 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
728 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
729 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
730 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
731 practice a lot first before you rely on it!