1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
|
<html>
<head>
<title>Idempotent Merging</title>
</head>
<body>
<a name="Idempotent_Merging"></a>
<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>
<h2 align=center>Idempotent Merging</h2>
<small>
<b>up: </b><a href="arch.html#arch">arch</a></br>
</small>
<br>
<p>[Idempotent merging is not implemented in the current release.]
</p><p>Let's suppose that we have a main development path, with several
branches:
</p><pre>
main
----
base-0
patch-1
patch-2-----------------------> branch-a
patch-3 |
patch-4 |
patch-5 |-----> branch-b
|
|
-----> branch-c
</pre>
<p>What happens if each of the three branches checks in a revision that
is an <code>update</code>
against the <code>main</code>
branch. In other words, each branch
will have a delta that that summarizes patches <code>3..5</code>
of the main
branch.
</p><p>If we try to <code>replay</code>
from two or more of those branches, we'll wind
up replaying several of those deltas that summarize <code>3..5</code>
. Those
patches will be redundant and will likely generate merge conflicts.
</p><p><code>Update</code>
won't do much better in this case. The common ancestor of
all three branches is their <code>base-0</code>
revision, which is the same as
<code>patch-2</code>
on <code>main</code>
.
</p><p>Now suppose I start with the latest revision on <code>branch-a</code>
, which
includes patches <code>3..5</code>
of the main branch, plus some changes specific
to <code>branch-a</code>
. And <code>branch-b</code>
is similar -- it has <code>3..5</code>
from <code>main</code>
some changes specific to <code>branch-b</code>
.
</p><p>If I <code>update</code>
my <code>branch-A</code>
revision against <code>branch-B</code>
, the <code>A</code>
revision is compared to the common ancestor. In essence:
</p><pre>
upate_patch = delta (branch-a--latest, main--patch-2)
</pre>
<p>Note that the update patch contains all the changes needed for <code>3..5</code>
from <code>main</code>
. <code>update</code>
will apply that patch to the latest revision of
<code>branch-B</code>
:
</p><pre>
update_a_from_b = update_patch [ branch-b--latest ]
</pre>
<p>but <code>branch-b--latest</code>
already includes patches <code>3..5</code>
from main.
There's a good chance the merge will have conflicts.
</p><p>When such messes occur, the <code>reconcile</code>
command, introduced in the
previous chapter, can help you out of them. But wouldn't it be better
to avoid such problems in the first place?
</p>
<a name="The_i-merge_Command"></a>
<h3 align=center>The i-merge Command</h3>
<p>A tool for tackling the problem directly is an <code>idempotent</code>
merge:
</p><pre>
% larch i-merge [ --update [ARCHIVE/]REVISION
| --replay [ARCHIVE/]REVISION ]
[ARCHIVE/]SOURCE-REVISION
directory
</pre>
<p>That creates a project tree in DIRECTORY by using <code>larch get</code>
to obtain
the <code>SOURCE-REVISION</code>
, then applying each of the specified <code>update</code>
and <code>replay</code>
commands, in the order specified.
</p><p>If any merge conflicts occur, the command issues an error, and leaves
the partially meged directory, along with an explanation of where it
left off.
</p><p>If the command succeeds, though, the project tree will be left in a
special state which permits the use of the <code>--idempotent</code>
flag to
<code>commit</code>
.
</p><pre>
% larch commit --idempontent
</pre>
<p>which, in fact, creates two new revisions. The first revision created
is the intermediate directory, containing only <code>SOURCE-REVISION</code>
plus
the series of <code>updates</code>
and <code>replays</code>
you specified -- no other
changes. The log message for this revision is automatically
generated, and has the special header <code>idempotent-merge:</code>
with the
list of patches applied.
</p><p>The second revision contains the log message you wrote, plus any
subsequent changes you made.
</p><p>When <code>reply</code>
wants to apply a patch set, it checks to see if it is an
idempotent patch set. If it is, and all of the patches included in
the patch set are missing from the tree being patched, <code>replay</code>
proceeds in the usual way: by applying the set of deltas in the patch
set.
</p><p>If some of the patches included in an idempotent merge have already
been applied to the tree being patched, then `<code>replay</code>
applies only
those patches not already included.
</p><p>One possible policy is that every branch should merge only from the
main branch, and should always merge from the main branch using an
idempotent update:
</p><pre>
% cd ~/wd
</pre>
<pre>
% larch i-merge --update main branch-a branch-a-merged
[...]
</pre>
<p>Each branch will then contain a number of idempotent patch sets, as in
this example:
</p><pre>
branch-a branch-b
-------- --------
base-0 base-0
patch-1 patch-1
patch-2..."idempotent merge w/main patches 2,3" patch-2
patch-3 "idempotent merge w/main patch 2"...patch-3
patch-4 patch-4
patch-5..."idempotent merge w/main patch 4" patch-5
patch-6 "idempotent merge w/main patch 3"...patch-6
patch-7..."idempotent merge w/main patch 5" patch-7
patch-8 patch-8
"idempotent merge w/main patches 4,5"...patch-9
patch-10
</pre>
<p>What if we want to form a merge of these two branches?
</p>
<a name="idempotent_Merges_and_the_replay_Command"></a>
<h3 align=center>idempotent Merges and the replay Command</h3>
<p>We can start with a project tree for the latest revision of <code>branch-a</code>
</p><pre>
% larch get ~/wd/branch-a
% cd ~/wd/branch-a
</pre>
<p><code>Branch-a</code>
does not already have a patch log for <code>branch-b</code>
, though
the two branches have a common ancestor, so <code>add-sibling-log</code>
will
solve that problem:
</p><pre>
% larch add-sibling-log branch-b
[....]
</pre>
<p>Now we can find out what the merge needs to do:
</p><pre>
% larch whats-missing branch-b
patch-1
patch-2
patch-3
patch-4
patch-5
patch-6
patch-7
patch-8
patch-9
patch-10
</pre>
<p>If we use <code>replay</code>
:
</p><pre>
% cd ~/wd
% larch replay ~/wd/branch-a ~/wd/branch-a-merged branch-b
</pre>
<p>These patches will be applied:
</p><pre>
branch-b/patch-1
branch-b/patch-2
branch-b/patch-4
branch-b/patch-5
branch-b/patch-7
branch-b/patch-8
branch-b/patch-10
</pre>
<p>Patches <code>3, 6, 9</code>
are skipped (though their log entries are added to
the project tree) because branch-a already has all of the patches
those idempotent patch sets include.
</p>
<a name="idempotent_Patch_Sets_and_the_update_Command"></a>
<h3 align=center>idempotent Patch Sets and the update Command</h3>
<p>What will <code>update</code>
do? It computes a patch between the project tree
being updated and the common ancestor:
</p><pre>
update_patch = delta (branch-a--patch-8, branch-b--base-0)
</pre>
<p>then applies that to the update revision:
</p><pre>
branch-a-mege = update_patch [ branch-b--patch-10 ]
</pre>
<p>The idempotent revisions don't help there. However....
</p>
<a name="idempotent_Patch_Sets_and_Partial_Updates"></a>
<h3 align=center>idempotent Patch Sets and Partial Updates</h3>
<p>The <code>--partial</code>
flag to the <code>update</code>
command takes advantage of
idempotent patch sets.
</p><p>As before, we assume these revisions:
</p><pre>
branch-a branch-b
-------- --------
base-0 base-0
patch-1 patch-1
patch-2..."idempotent merge w/main patches 2,3" patch-2
patch-3 "idempotent merge w/main patch 2"...patch-3
patch-4 patch-4
patch-5..."idempotent merge w/main patch 4" patch-5
patch-6 "idempotent merge w/main patch 3"...patch-6
patch-7..."idempotent merge w/main patch 5" patch-7
patch-8 patch-8
"idempotent merge w/main patches 4,5"...patch-9
patch-10
</pre>
<p>We have a tree for <code>branch-a--patch-8</code>
and it's ancestor on <code>branch-b</code>
is <code>base-0</code>
. So:
</p><pre>
% cd ~/wd/branch-a--patch-8
% larch whats-missing branch-b
patch-1
patch-2
patch-3
patch-4
patch-5
[...]
patch-10
</pre>
<p>If we use:
</p><pre>
% larch update --partial ~/wd/branch-a--patch-8 \
~/wd/branch-a-b-partial-update \
branch-b
</pre>
<p>then <code>update</code>
uses not the latest revision of <code>branch-b</code>
, but the
revision just prior to the oldest idempotent patch set that <code>branch-a</code>
does not yet have. In this case, <code>patch-3</code>
of branch-b is the oldest
idempotent patch that <code>branch-a</code>
is missing. So:
</p><pre>
% larch update --partial ~/wd/branch-a--patch-8 \
~/wd/branch-a-b-partial-update \
branch-b
</pre>
<p>is eqivalent to:
</p><pre>
% larch update --partial ~/wd/branch-a--patch-8 \
~/wd/branch-a-b-partial-update \
branch-b--patch-2
</pre>
<p>After which:
</p><pre>
% cd ~/wd/branch-a-b-partial-update
% larch whats-missing branch-b
patch-3
patch-4
patch-5
[...]
patch-10
</pre>
<p>When the earliest missing patch prior to a partial update is an
idempotent patch set, and the tree already has all of the patches
included in that patch set, <code>update</code>
simply adds the log message for
the idempotent patch to the tree being patched, and stops.
</p><p>If the tree being patched has <em>none</em> of the patches included in that
patch set, <code>update</code>
updates against the idempotent revision in the
normal way.
</p><p>Finally, if the tree being patch has <em>some</em> but not all of the patches
included in the idempotent patch set, <code>udpate</code>
gives up with an error
and suggests that you use <code>replay</code>
to apply the idempotent patch set.
(In a future release, <code>update</code>
will do something more intellegent in
this case).
</p><p>The upshot of this is that you can merge branches <code>A</code>
and <code>B</code>
with a
series of partial updates and replays:
</p><pre>
# update against patch-level 2
#
% larch update --partial ~/wd/branch-a--patch-8
~/wd/branch-a-b-partial-update
branch-b
</pre>
<pre>
# replay patch-level 3
# -- we already have all the patches included in the
# idempotent branch-b patch, "patch-3" - so all this
# really does is install a log message.
#
% larch replay ~/wd/branch-a-b-partial-update
~/wd/branch-a-b-partial-update-2
branch-b--patch-3
</pre>
<pre>
# update against patch-level 5
#
% larch update --partial ~/wd/branch-a-b-partial-update-2
~/wd/branch-a-b-partial-update-3
branch-b
</pre>
<pre>
% larch replay ~/wd/branch-a-b-partial-update-3
~/wd/branch-a-b-partial-update-4
branch-b--patch-5
</pre>
<pre>
% larch update --partial ~/wd/branch-a-b-partial-update-5
~/wd/branch-a-b-partial-update-6
branch-b
</pre>
<pre>
% larch replay ~/wd/branch-a-b-partial-update-6
~/wd/branch-a-b-partial-update-7
branch-b--patch-9
</pre>
<pre>
% larch update --partial ~/wd/branch-a-b-partial-update-9
~/wd/branch-a-b-merged
branch-b
</pre>
<small><i>arch: The arch Revision Control System
</i></small><br>
<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>
</body>
|
