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
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
|
<html>
<head>
<title>The arch Global Name-space of Projects</title>
</head>
<body>
<a name="The_arch_Global_Name-space_of_Projects"></a>
<a href="http://www.regexps.com">The Hackerlab at <code>regexps.com</code></a>
<h2 align=center>The arch Global Name-space of Projects</h2>
<small>
<b>up: </b><a href="arch.html#arch">arch</a></br>
<b>next: </b><a href="archives.html#Archives">Archives</a></br>
<b>prev: </b><a href="user-names.html#The_arch_Global_Name-space_of_Users">The arch Global Name-space of Users</a></br>
</small>
<br>
<p>Another central organizing concept of <code>arch</code>
is a global namespace of
projects.
</p><p>This chapter describes how projects are named, and how the names are
applied to project trees.
</p><ul>
<li><a href="project-names.html#The_Structure_of_Project_Names">The Structure of Project Names</a></li>
<li><a href="project-names.html#Archive_Names">Archive Names</a></li>
<li><a href="project-names.html#Category_Names_and_Branch_Labels">Category Names and Branch Labels</a></li>
<li><a href="project-names.html#Version_Numbers">Version Numbers</a></li>
<li><a href="project-names.html#Labelling_Project_Trees">Labelling Project Trees</a></li>
<li><a href="project-names.html#Combining_Project_Trees">Combining Project Trees</a></li>
</ul>
<hr>
<a name="The_Structure_of_Project_Names"></a>
<h3 align=center>The Structure of Project Names</h3>
<small>
<b>up: </b><a href="project-names.html#The_arch_Global_Name-space_of_Projects">The arch Global Name-space of Projects</a></br>
<b>next: </b><a href="project-names.html#Archive_Names">Archive Names</a></br>
</small>
<br>
<p>The <code>arch</code>
project name-space is designed to reflect the intricacies
of how projects evolve in the real world. For example, two or more
different organizations may separately develop and distribute a given
project. A project can split into multiple development paths. Each
path typically evolves through a series of versions. <code>arch</code>
provides
a way to precisely name all of these different instances of a given
project.
</p><p>An <code>arch</code>
project name has four basic parts, introduced here, and
explained in detail below.
</p><p><strong><u>An Archive Name</u></strong> The <em>
<a name="index-pt:0"></a>
archive name
</em>
identifies the organization that
distributes particular versions of a project. Some example archive
names might be:
</p><pre>
hackerlab@regexps.com--hackerlab
hurd@gnu.org--hurd-team
</pre>
<p><strong><u>The Category Name</u></strong> The <em>
<a name="index-pt:1"></a>
category name
</em>
is a generic name for the
project. It is what people usually think of as a "project name".
Some example category names are:
</p><pre>
arch
gcc
rx
</pre>
<p><strong><u>The Branch Label</u></strong> When a project splits into multiple development
paths (even if only temporarilly -- as a convenience to the
maintainers), each path is given a <em>
<a name="index-pt:2"></a>
branch label
</em>
. Some example
branch labels are:
</p><pre>
development
experimental
</pre>
<p><strong><u>The Version Number</u></strong> <code>arch</code>
uses fairly simple <em>
<a name="index-pt:3"></a>
version numbers
</em>
,
consisting of a major and minor version number:
</p><pre>
1.2
2.0
</pre>
<p>The four parts of a project name fit together this way:
</p><pre>
<archive-name>/<category>[--<branch-label>]--<version-number>
</pre>
<p>As in the example:
</p><pre>
hackerlab@regexps.com--hackerlab/arch--development--2.0
^ ^ ^ ^
| | | |
archive name category branch version
label
</pre>
<p>Notice that the archive name is separated from the rest of the project
name by <code>/</code>
. The other parts of the project name are separated by
<code>--</code>
.
</p><p>When you use <code>arch</code>
, you often abbreviate project names. For example,
you can leave off the archive name and a default archive will be
presumed:
</p><pre>
arch--development--2.0
</pre>
<p>or you can leave off the version number and, depending on context,
that means either "the latest version" or "all versions":
</p><pre>
arch--development
</pre>
<p>If you have one branch which is "primary branch", you can leave out
the branch label:
</p><pre>
arch--2.0
hackerlab@regexps.com--hackerlab/arch--2.0
arch
hackerlab@regexps.com--hackerlab/arch
</pre>
<p>Those last two names are also sometimes used to mean "every branch of
arch" or "every branch of arch at the hackerlab archive",
respectively.
</p>
<hr>
<a name="Archive_Names"></a>
<h3 align=center>Archive Names</h3>
<small>
<b>up: </b><a href="project-names.html#The_arch_Global_Name-space_of_Projects">The arch Global Name-space of Projects</a></br>
<b>next: </b><a href="project-names.html#Category_Names_and_Branch_Labels">Category Names and Branch Labels</a></br>
<b>prev: </b><a href="project-names.html#The_Structure_of_Project_Names">The Structure of Project Names</a></br>
</small>
<br>
<p><a name="index-pt:4"></a>
</p><p>An <em>
<a name="index-pt:5"></a>
archive name
</em>
designates an organization that develops and/or
distributes software. Archive names should be globally unique.
</p><p>Later in the manual, we'll see that archive names are specifically
used to identify revision control archives.
</p><p>An archive name consists of an email address (with complete hostname),
followed by <em>
<a name="index-pt:6"></a>
--
</em>
, followed by an additional string of numbers, letters
and dashes. Choose an email address which is exclusively yours (or
your project's). That way, your archive name(s) will be globally unique.
Here is an example:
</p><pre>
joe.hacker@gnu.org--test-archive
</pre>
<p>If your organization is going to have more than one revision control
archive, you'll use more than one archive name:
</p><pre>
joe.hacker@gnu.org--gcc-archive
joe.hacker@gnu.org--guile-archive
joe.hacker@gnu.org--2001
</pre>
<p>You can choose an archive name to use as the default for all <code>arch</code>
commands. When you run a command without explicitly specifying a
archive, the default is used:
</p><pre>
% larch my-default-archive joe.hacker@gnu.org--2001
</pre>
<p>To find out the current default:
</p><pre>
% larch my-default-archive
joe.hacker@gnu.org--2001
</pre>
<p>In general, <code>arch</code>
sub-commands accept the option <code>-A</code>
to specify a
non-default archive:
</p><pre>
% larch my-default-archive -A joe.hacker@gnu.org--test-archive
joe.hacker@gnu.org--test-archive
</pre>
<hr>
<a name="Category_Names_and_Branch_Labels"></a>
<h3 align=center>Category Names and Branch Labels</h3>
<small>
<b>up: </b><a href="project-names.html#The_arch_Global_Name-space_of_Projects">The arch Global Name-space of Projects</a></br>
<b>next: </b><a href="project-names.html#Version_Numbers">Version Numbers</a></br>
<b>prev: </b><a href="project-names.html#Archive_Names">Archive Names</a></br>
</small>
<br>
<p>The <em>
<a name="index-pt:7"></a>
category
</em>
of a project name identifies, generally, what the
project is. The category is the same no matter who is distributing
the project, or which development path is being considered.
</p><p>The <em>
<a name="index-pt:8"></a>
branch label
</em>
is optional. It can be used to distinguish
alternative development paths for a given project.
</p><p>The <em>
<a name="index-pt:9"></a>
category
</em>
and <em>
<a name="index-pt:10"></a>
branch label
</em>
must match the regexp:
</p><pre>
[[:alpha:]]([[:alnum:]]*(-[[:alnum:]]+)?)*
</pre>
<p>or in other words, they must begin with a letter and consist entirely
of digits, letters, and dashes -- but must not contain two dashes in a
row, and must not end with a dash.
</p>
<hr>
<a name="Version_Numbers"></a>
<h3 align=center>Version Numbers</h3>
<small>
<b>up: </b><a href="project-names.html#The_arch_Global_Name-space_of_Projects">The arch Global Name-space of Projects</a></br>
<b>next: </b><a href="project-names.html#Labelling_Project_Trees">Labelling Project Trees</a></br>
<b>prev: </b><a href="project-names.html#Category_Names_and_Branch_Labels">Category Names and Branch Labels</a></br>
</small>
<br>
<p>In a somewhat arbitrary but extremely traditional way, branches are
divided into a series of versions.
</p><p>The <em>
<a name="index-pt:11"></a>
version number
</em>
must match the regexp:
</p><pre>
[[:digit:]]+\\.[[:digit:]]+
</pre>
<p>or in other words, it must consist of two strings of digits, separated
by a single period. The first string of digits is called the <em>
<a name="index-pt:12"></a>
major
version number
</em>
and the second string of digits is called the <em>
<a name="index-pt:13"></a>
minor
version number
</em>
.
</p><p><strong><u>Note:</u></strong> <em>Version numbers</em> are not <em>revision numbers</em>. In other words,
when the <code>arch</code>
revision control system stores multiple snapshots of
the development of your project, it does <em>not</em> assign a new version
number to each snapshot. Instead, each project version is further
subdivided into something called "patch levels", which are explained
in detail later in the manual.
</p>
<hr>
<a name="Labelling_Project_Trees"></a>
<h3 align=center>Labelling Project Trees</h3>
<small>
<b>up: </b><a href="project-names.html#The_arch_Global_Name-space_of_Projects">The arch Global Name-space of Projects</a></br>
<b>next: </b><a href="project-names.html#Combining_Project_Trees">Combining Project Trees</a></br>
<b>prev: </b><a href="project-names.html#Version_Numbers">Version Numbers</a></br>
</small>
<br>
<p><a name="index-pt:14"></a>
<a name="index-pt:15"></a>
</p><p>Every project tree may be labeled with a project name using the
<code>set-tree-version</code>
command, as in this example:
</p><pre>
% cd ~/wd/arch
% larch set-tree-version arch--1.0
</pre>
<p>That project name becomes the default for <code>arch</code>
operations within
that tree.
</p><p>You can find out the project name of a tree with <code>tree-version</code>
:
</p><pre>
% larch tree-version
joe.hacker@gnu.org--2001/arch--1.0
</pre>
<p>Notice that <code>arch</code>
used the default archive (returned by
<code>my-default-archive</code>
) when <code>set-tree-version</code>
was invoked. You can
also specify an archive explicitly, as in these two examples:
</p><pre>
% larch set-tree-version joe.hacker@gnu.org--alt/arch--1.0
</pre>
<p>or
</p><pre>
% larch set-tree-version -A joe.hacker@gnu.org--alt arch--1.0
</pre>
<hr>
<a name="Combining_Project_Trees"></a>
<h3 align=center>Combining Project Trees</h3>
<small>
<b>up: </b><a href="project-names.html#The_arch_Global_Name-space_of_Projects">The arch Global Name-space of Projects</a></br>
<b>prev: </b><a href="project-names.html#Labelling_Project_Trees">Labelling Project Trees</a></br>
</small>
<br>
<p>You can, in fact, combine project trees: storing the files and
directories from multiple projects under a common root. This can be
useful if you have separately maintained projects that, nevertheless,
are tightly integrated. This is explained in a later chapter (xref!!!).
</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>
|
