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
|
<html>
<head>
<title>arch Patch Sets</title>
</head>
<body>
<a name="arch_Patch_Sets"></a>
<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>
<h2 align=center>arch Patch Sets</h2>
<small>
<b>up: </b><a href="arch.html#arch">arch</a></br>
<b>prev: </b><a href="inventory.html#arch_Project_Inventories">arch Project Inventories</a></br>
</small>
<br>
<p><a name="index-pt:0"></a>
</p><p>It is often extremely useful to compare two project trees (usually for
the same project) and figure out exactly what has changed between
them. A record of such changes is called a <em>
<a name="index-pt:1"></a>
patch set
</em>
or a <em>
<a name="index-pt:2"></a>
delta
</em>
.
</p><p>If you have a patch set between an "old tree" and a "new tree",
you can "apply the patch" to the old tree to get the new tree -- in
other words, you can automatically make the editting changes described
by a patch set. If you have some third tree, you can apply the patch
to get an approximation of making the same changes to that third tree.
(see <a href="theory-of-patches.html#The_Theory_of_Patches_and_Revisions">The Theory of Patches and Revisions</a>).
</p><p><code>arch</code>
includes sophisticated tools for creating and applying patch sets.
</p><ul>
<li><a href="patches.html#mkpatch">mkpatch</a></li>
<li><a href="patches.html#dopatch">dopatch</a></li>
<li><a href="patches.html#Inexact_Patching">Inexact Patching</a></li>
</ul>
<hr>
<a name="mkpatch"></a>
<h3 align=center>mkpatch</h3>
<small>
<b>up: </b><a href="patches.html#arch_Patch_Sets">arch Patch Sets</a></br>
<b>next: </b><a href="patches.html#dopatch">dopatch</a></br>
</small>
<br>
<p><a name="index-pt:3"></a>
<a name="index-pt:4"></a>
</p><p><code>mkpatch</code>
computes a patch set describing the differences between two
trees. The basic command syntax is:
</p><pre>
% mkpatch ORIGINAL MODIFIED DESTINATION
</pre>
<p>which compares the trees <code>ORIGINAL</code>
and <code>MODIFIED</code>
.
</p><p><code>mkpatch</code>
creates a new directory, <code>DESTINATION</code>
, and stores the patch
set there.
</p><p>When <code>mkpatch</code>
compares trees, it uses inventory tags. For example,
it considers two directories or two files to be "the same directory
(or file)" if they have the same tag -- regardless of where each is
located in its respective tree.
</p><p>A patch set produced by <code>mkpatch</code>
describes what files and directories
have been added or removed, which have been renamed, which files have
been changed (and how they have been changed), and what file
permissions have changed (and how). When regular text files are
compared, <code>mkpatch</code>
produces a context diff describing the
differences. <code>mkpatch</code>
can compare binary files (saving complete
copies of the old and new versions if they differ) and symbolic links
(saving the old and new link targets, if they differ).
</p><p>A detailed description of the format of a patch set is provided in an
appendix (see <a href="patch-set-format.html#The_arch_Patch_Set_Format">The arch Patch Set Format</a>).
</p>
<hr>
<a name="dopatch"></a>
<h3 align=center>dopatch</h3>
<small>
<b>up: </b><a href="patches.html#arch_Patch_Sets">arch Patch Sets</a></br>
<b>next: </b><a href="patches.html#Inexact_Patching">Inexact Patching</a></br>
<b>prev: </b><a href="patches.html#mkpatch">mkpatch</a></br>
</small>
<br>
<p><a name="index-pt:5"></a>
</p><p><code>dopatch</code>
is used to apply a patch set to tree:
</p><pre>
% dopatch patch-set tree
</pre>
<p>If <code>tree</code>
is exactly the same as the the "original" tree seen by
<code>mkpatch</code>
, then the effect is to modify <code>tree</code>
so that it is exactly
the same as the the "modified" tree seen by <code>mkpatch</code>
, with one
exception (explained below).
</p><p>"Exactly the same" means that the directory structure is the same,
symbolic link targets are the same, the contents of regular files are
the same, and file permissions are the same. Modification times,
files with multiple (hard) links, and file ownership are not reliably
preserved.
</p><p>The exception to the "exactly the same" rule is that if the patch
requires that files or directories be removed from <code>tree</code>
, those files
and directories will be saved in a subdirectory of <code>tree</code>
with an
eye-splitting name matching the pattern:
</p><pre>
++removed-by-dopatch-PATCH--DATE
</pre>
<p>where <code>PATCH</code>
is the name of the patch-set directory and <code>DATE</code>
a
timestamp.
</p><p>At this time, <code>dopatch</code>
does not support reverse patching, though this
is likely to be added in a future release.
</p>
<hr>
<a name="Inexact_Patching"></a>
<h3 align=center>Inexact Patching</h3>
<small>
<b>up: </b><a href="patches.html#arch_Patch_Sets">arch Patch Sets</a></br>
<b>prev: </b><a href="patches.html#dopatch">dopatch</a></br>
</small>
<br>
<p><a name="index-pt:6"></a>
<a name="index-pt:7"></a>
</p><p>What if a tree patched by <code>dopatch</code>
is not exactly the same as the
original tree seen by <code>mkpatch</code>
?
</p><p>Below is a brief description of what to expect. Complete
documentation of the <code>dopatch</code>
process is included with the source
code.
</p><p><code>dopatch</code>
takes an inventory of the tree being patched. It uses
inventory tags to decide which files and directories expected by the
patch set are present or missing from the tree, and to figure out
where each file and directory is located in the tree.
</p><p><strong><u>Simple Patches</u></strong> If the patch set contains an ordinary patch or
metadata patch for a link, directory or file, and that file is present
in the tree, <code>dopatch</code>
applies the patch in the ordinary way. If the
patch applies cleanly, the modified file, link, or directory is left
in place.
</p><p>If a simple patch fails to apply cleanly, <code>dopatch</code>
will always leave
behind a <code>.orig</code>
file (the file originally in the tree being patched,
without any changes) and a <code>.rej</code>
file (the part of the patch that
could not be applied).
</p><p>If the patch was a context diff, <code>dopatch</code>
will also leave behind the
file itself -- partially patched.
</p><p>If an (unsucessful) patch was for a binary file, no partially-patched
file will be left. Instead, there will be:
</p><pre>
.orig -- the file originally in the tree being patched,
without modifications.
</pre>
<pre>
.rej -- a complete copy of the file from the modified tree,
with permissions copied from `.orig'.
</pre>
<pre>
.patch-orig -- a complete copy of the file from the original
tree seen by `mkpatch', with permissions
retained from that original
</pre>
<pre>
-or-
</pre>
<pre>
the symbolic link from the original tree seen
by `mkpatch' with permissions as in the original
tree.
</pre>
<p>If an (unsucessful) patch was for a symbolic link, no partially
patched file will be left. Instead there will be:
</p><pre>
.orig -- the unmodified file from the original tree
</pre>
<pre>
.rej -- a symbolic link with the target intended by the
patch and permissions copied from .orig
</pre>
<pre>
.patch-orig -- a complete copy of the file from the original
tree seen by `mkpatch', with permissions
retained from that original
</pre>
<pre>
-or-
</pre>
<pre>
the symbolic link from the original tree seen
by `mkpatch' with permissions as in the original
tree.
</pre>
<p><strong><u>Patches for Missing Files</u></strong>
</p><p>All patches for missing files and directories are stored in a
subdirectory of the root of the tree being patched called
</p><pre>
==missing-file-patches-PATCH-DATE
</pre>
<p>where <code>PATCH</code>
is the basename of the patch set directory and <code>DATE</code>
a
time-stamp.
</p><p><strong><u>Directory Rearrangements and New Directories</u></strong>
</p><p>Directories are added, deleted, and rearranged much as you would
expect, even if you don't know it's what you'd expect.
</p><p>Suppose that when <code>mkpatch</code>
was called the <code>ORIGINAL</code>
tree had:
</p><pre>
Directory or file: Tag:
</pre>
<pre>
a/x.c tag_1
a/bar.c tag_2
</pre>
<p>but the <code>MODIFIED</code>
tree had:
</p><pre>
a/x.c tag_1
a/y.c tag_2
</pre>
<p>with changes to both files. The patch will want to rename the file
with tag <code>tag_2</code>
to <code>y.c</code>
, and change the contents of the files with
tags <code>tag_1</code>
and <code>tag_2</code>
.
</p><p>Suppose, for example, that you have a tree with:
</p><pre>
a/foo.c tag_1
a/zip.c tag_2
</pre>
<p>and the you apply the patch to that tree. After the patch, you'll be
left with:
</p><pre>
a/foo.c tag_1
a/y.c (was zip.c) tag_2
</pre>
<p>with patches made to the contents of both files.
</p><p>Here's a sample of some subtleties and ways of handling conflicts:
</p><p>Suppose that the original tree seen by mkpatch has:
</p><pre>
Directory or file: Tag:
</pre>
<pre>
./a tag_a
./a/b tag_b
./a/b/c tag_c
</pre>
<p>and that the modified directory has:
</p><pre>
./a tag_a
./a/c tag_c
./a/c/b tag_b
</pre>
<p>Finally, suppose that the tree has:
</p><pre>
./x tag_a
./x/b tag_b
./x/c tag_new_directory
./x/c/b tag_diffent_file_named_b
./x/c/q tag_c
</pre>
<p>When patch gets done with the tree, it will have:
</p><pre>
./x tag_a
Since the patch doesn't do anything
to change the directory with tag_a.
</pre>
<pre>
./x/c.orig tag_new_directory
./x/c.rej tag_c
Since the patch wants to make the
directory with tag_c a subdirectory named "c"
of the directory with tag_a, but the tree
already had a different directory there,
with the tag tag_new_directory.
</pre>
<pre>
./x/c.rej/b tag_b
Since the patch wants to rename the directory
with tag_b to be a subdirectory named "b"
of the directory with tag_c.
</pre>
<pre>
./x/c.orig/b tag_diffent_file_named_b
Since the patch made new changes to this file,
it stayed with its parent directory.
</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>
|
