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
|
<html>
<head>
<title>Revision Tree Libraries</title>
</head>
<body>
<a name="Revision_Tree_Libraries"></a>
<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>
<h2 align=center>Revision Tree Libraries</h2>
<small>
<b>up: </b><a href="arch.html#arch">arch</a></br>
<b>next: </b><a href="triggers.html#arch_Triggers">arch Triggers</a></br>
</small>
<br>
<p><a name="index-pt:0"></a>
</p><p>For many purposes, it is useful to have a library containing pristine
trees of a large number of revisions -- for example, all of the
revisions in a particular version. To be practical, though, such a
library must be represented in a space-efficient way.
</p><p>Unix hard-links provide a natural way to store such a library. Each
successive revision in a series is a copy of the previous, but with
unmodified files shared via hard-links.
</p><p><code>arch</code>
provides commands to help you build, maintain, and browse such
a library.
</p>
<a name="Your_Revision_Library_Location"></a>
<h3 align=center>Your Revision Library Location</h3>
<p><a name="index-pt:1"></a>
</p><p>To begin a new revision library, first create a new directory (<code>DIR</code>
)
and then register its location:
</p><pre>
% larch my-revision-library DIR
</pre>
<p>You can check the location of your library with:
</p><pre>
% larch my-revision-library
</pre>
<p>or unregister it with:
</p><pre>
% larch my-revision-library -d
</pre>
<a name="Revision_Library_Format"></a>
<h3 align=center>Revision Library Format</h3>
<p>A revision library has subdirectories of the form:
</p><pre>
ARCHIVE-NAME/CATEGORY/BRANCH/VERSION/REVISION/
</pre>
<p>Each <code>REVISION</code>
directory contains the complete source of a particular
revision, along with some supplemantary subdirectories and files:
</p><pre>
REVISION/,,patch-set/
</pre>
<pre>
The patch set that creates this revision from
its ancestor (unless the revision is a full-source
base revision).
</pre>
<p>Although the permissions on files in the revision library are
determined as determined by patch sets, <strong>you must never modify files
int the revision library</strong>. Doing so will cause odd errors and
failures in various <code>arch</code>
commands.
</p>
<a name="Adding_a_Revision_to_the_Library"></a>
<h3 align=center>Adding a Revision to the Library</h3>
<p><a name="index-pt:2"></a>
</p><p>You can add a selected revision to your revision library with:
</p><pre>
% larch library-add REVISION
</pre>
<p>That will add not only <code>REVISION</code>
to the library, but all directly
preceeding revisions (recursively) which are either from the same
archive, or from other archives which are also in the same library.
("Directly preceeding" in this case means the previous patch level,
for ordinary revisions, or the tagged revision (for revisions which
are tags).)
</p>
<a name="Finding_a_Revision_in_the_Library"></a>
<h3 align=center>Finding a Revision in the Library</h3>
<p><a name="index-pt:3"></a>
</p><p>You can find a particular revision in the library with <code>library-find</code>
:
</p><pre>
% larch library-find REVISION
PATH-TO-REVSION
</pre>
<p>The output is an absolute path name to the library directory containing
the revision. (Once again, you must not modify files in that
directory.)
</p>
<a name="Removing_a_Revision_from_the_Library"></a>
<h3 align=center>Removing a Revision from the Library</h3>
<p><a name="index-pt:4"></a>
</p><p>To remove a particular revision from the library, use:
</p><pre>
% larch library-remove REVISION
</pre>
<p>Be aware of the following limitation in the current release: suppose
that you add three successive revisions, <code>A</code>
, <code>B</code>
, and <code>C</code>
. Then you
remove <code>B</code>
, then re-add <code>B</code>
. Now there is a chance that the file
sharing between <code>B</code>
and <code>C</code>
will be less than optimal, causing your
library to be larger than it needs to be. (You can fix this by then
removing and re-adding <code>C</code>
.)
</p>
<a name="Listing_Library_Contents"></a>
<h3 align=center>Listing Library Contents</h3>
<p><a name="index-pt:5"></a>
<a name="index-pt:6"></a>
<a name="index-pt:7"></a>
<a name="index-pt:8"></a>
<a name="index-pt:9"></a>
</p><p>The command <code>library-archives</code>
lists all archives with records in the library:
</p><pre>
% larch library-archive
ARCHIVE-NAME
ARCHIVE-NAME
...
</pre>
<p>Similarly, you can list categories, branches, versions, or revisions:
</p><pre>
% larch library-categories [ARCHIVE]
% larch library-branches [ARCHIVE/CATEGORY]
% larch library-versions [ARCHIVE/BRANCH]
% larch library-revisions [ARCHIVE/VERSION]
</pre>
<a name="Individual_Files_in_the_Revision_Library"></a>
<h3 align=center>Individual Files in the Revision Library</h3>
<p><a name="index-pt:10"></a>
<a name="index-pt:11"></a>
</p><p>You can locate an individual file in a revision library with:
</p><pre>
% archive library-file FILE [REVISION]
PATH
</pre>
<p>or obtain its contents with:
</p><pre>
% archive cat-library-file FILE [REVISION]
...file contents...
</pre>
<p>Both commands accept the options <code>--tag</code>
and <code>--this</code>
. With <code>--tag</code>
,
the argument <code>FILE</code>
is interpreted as an inventory tag, and the file
with that tag is found.
</p><p>With <code>--this</code>
, <code>FILE</code>
is interpreted as a file relative to the current
directory, which should be part of a project tree. The file's
inventory tag is computed and the corresponding file found in
<code>REVISION</code>
.
</p>
<a name="Determining_Patch_Set_Prerequisits"></a>
<h3 align=center>Determining Patch Set Prerequisits</h3>
<p><a name="index-pt:12"></a>
</p><pre>
% larch touched-files-prereqs REVISION
</pre>
<p>That command looks at the patch set for <code>REVISION</code>
and at all
preceding patch sets in the same version (it searches your library
rather than your repository for this purpose). It reports the list of
patches that touch overlapping sets of files and directories -- in
other words, it tells you what patches can be applied independently of
others. The command has an option to exclude from consideration file
names matching a certain pattern (e.g. <em>
<a name="index-pt:13"></a>
=README
</em>
or <em>
<a name="index-pt:14"></a>
ChangeLog
</em>
). It
has an option to exclude from the output list patches which have
already been applied to a given project tree. It has an option to
report the specific files which are overlapped.
</p>
<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>
|
