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
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
|
.\" $Id: cvshelp.man,v 1.1.1.3 1995/08/28 16:20:28 jimb Exp $
.\" Contributed by Lowell Skoog <fluke!lowell@uunet.uu.net>
.\" Full space in nroff; half space in troff
.de SP
.if n .sp
.if t .sp .5
..
.\" Start a command example
.de XS
.SP
.in +.5i
.ft B
.nf
..
.\" End a command example
.de XE
.fi
.ft P
.in -.5i
.SP
..
.TH CVSHELP LOCAL "17 March 1991" FLUKE
.SH NAME
cvshelp \- advice on using the Concurrent Versions System
.SH DESCRIPTION
This man page is based on experience using CVS.
It is bound to change as we gain more experience.
If you come up with better advice than is found here,
contact the Software Technology
Group and we will add it to this page.
.SS "Getting Started"
Use the following steps to prepare to use CVS:
.TP
\(bu
Take a look at the CVS manual page to see what it can do for you, and
if it fits your environment (or can possibly be made to fit your
environment).
.XS
man cvs
.XE
If things look good, continue on...
.TP
\(bu
Setup the master source repository. Choose a directory with
ample disk space available for source files. This is where the RCS
`,v' files will be stored. Say you choose
.B /src/master
as the root
of your source repository. Make the
.SB CVSROOT.adm
directory in the root of the source repository:
.XS
mkdir /src/master/CVSROOT.adm
.XE
.TP
\(bu
Populate this directory with the
.I loginfo
and
.I modules
files from the
.B "/usr/doc/local/cvs"
directory. Edit these files to reflect your local source repository
environment \- they may be quite small initially, but will grow as
sources are added to your source repository. Turn these files into
RCS controlled files:
.XS
cd /src/master/CVSROOT.adm
ci \-m'Initial loginfo file' loginfo
ci \-m'Initial modules file' modules
.XE
.TP
\(bu
Run the command:
.XS
mkmodules /src/master/CVSROOT.adm
.XE
This will build the
.BR ndbm (3)
file for the modules database.
.TP
\(bu
Remember to edit the
.I modules
file manually when sources are checked
in with
.B checkin
or CVS
.BR add .
A copy of the
.I modules
file for editing can be retrieved with the command:
.XS
cvs checkout CVSROOT.adm
.XE
.TP
\(bu
Have all users of the CVS system set the
.SM CVSROOT
environment variable appropriately to reflect the placement of your
source repository. If the above example is used, the following
commands can be placed in a
.I .login
or
.I .profile
file:
.XS
setenv CVSROOT /src/master
.XE
for csh users, and
.XS
CVSROOT=/src/master; export CVSROOT
.XE
for sh users.
.SS "Placing Locally Written Sources Under CVS Control"
Say you want to place the `whizbang' sources under
CVS control. Say further that the sources have never
been under revision control before.
.TP
\(bu
Move the source hierarchy (lock, stock, and barrel)
into the master source repository:
.XS
mv ~/whizbang $CVSROOT
.XE
.TP
\(bu
Clean out unwanted object files:
.XS
cd $CVSROOT/whizbang
make clean
.XE
.TP
\(bu
Turn every file in the hierarchy into an RCS controlled file:
.XS
descend \-f 'ci \-t/dev/null \-m"Placed under CVS control" \-nV\fR\fIx\fR\fB_\fR\fIy\fR\fB *'
.XE
In this example, the initial release tag is \fBV\fIx\fB_\fIy\fR,
representing version \fIx\fR.\fIy\fR.
.LP
You can use CVS on sources that are already under RCS control.
The following example shows how.
In this example, the source package is called `skunkworks'.
.TP
\(bu
Move the source hierarchy into the master source
repository:
.XS
mv ~/skunkworks $CVSROOT
.XE
.TP
\(bu
Clean out unwanted object files:
.XS
cd $CVSROOT/skunkworks
make clean
.XE
.TP
\(bu
Clean out unwanted working files, leaving only the RCS `,v' files:
.XS
descend \-r rcsclean
.XE
Note: If any working files have been checked out and changed,
.B rcsclean
will fail. Check in the modified working files
and run the command again.
.TP
\(bu
Get rid of
.SB RCS
subdirectories. CVS does not use them.
.XS
descend \-r \-f 'mv RCS/*,v .'
descend \-r \-f 'rmdir RCS'
.XE
.TP
\(bu
Delete any unwanted files that remain in the source hierarchy. Then
make sure all files are under RCS control:
.XS
descend \-f 'ci \-t/dev/null \-m"Placed under CVS control" \-n\fR\fItag\fR\fB *'
.XE
.I tag
is the latest symbolic revision tag that you applied to your package
(if any). Note: This command will probably generate lots of error
messages (for directories and existing RCS files) that you can
ignore.
.SS "Placing a Third-Party Source Distribution Under CVS Control"
The
.B checkin
command checks third-party sources into CVS. The
difference between third-party sources and locally
written sources is that third-party sources must be checked into a
separate branch (called the
.IR "vendor branch" )
of the RCS tree. This makes it possible to merge local changes to
the sources with later releases from the vendor.
.TP
\(bu
Save the original distribution kit somewhere. For example, if the
master source repository is
.B /src/master
the distribution kit could be saved in
.BR /src/dist .
Organize the distribution directory so that each release
is clearly identifiable.
.TP
\(bu
Unpack the package in a scratch directory, for example
.BR ~/scratch .
.TP
\(bu
Create a repository for the package.
In this example, the package is called `Bugs-R-Us 4.3'.
.XS
mkdir $CVSROOT/bugs
.XE
.TP
\(bu
Check in the unpacked files:
.XS
cd ~/scratch
checkin \-m 'Bugs-R-Us 4.3 distribution' bugs VENDOR V4_3
.XE
There is nothing magic about the tag `VENDOR', which is applied to
the vendor branch. You can use whatever tag you want. `VENDOR' is a
useful convention.
.TP
\(bu
Never modify vendor files before checking them in.
Check in the files
.I exactly
as you unpacked them.
If you check in locally modified files, future vendor releases may
wipe out your local changes.
.SS "Working With CVS-Controlled Sources"
To use or edit the sources, you must check out a private copy.
For the following examples, the master files are assumed to reside in
.BR "$CVSROOT/behemoth" .
The working directory is
.BR "~/work" .
See
.BR cvs (local)
for more details on the commands mentioned below.
.TP
.I "To Check Out Working Files
Use CVS
.BR checkout :
.XS
cd ~/work
cvs checkout behemoth
.XE
There is nothing magic about the working directory. CVS will check
out sources anywhere you like. Once you have a working copy of the
sources, you can compile or edit them as desired.
.TP
.I "To Display Changes You Have Made"
Use CVS
.BR diff
to display detailed changes, equivalent to
.BR rcsdiff (local).
You can also use
.BR cvscheck (local)
to list files added, changed, and removed in
the directory, but not yet
.BR commit ted.
You must be in a directory containing working files.
.TP
.I "To Display Revision Information"
Use CVS
.BR log ,
which is equivalent to
.BR rlog (local).
You must be in a directory containing working files.
.TP
.I "To Update Working Files"
Use CVS
.BR update
in a directory containing working files.
This command brings your working files up
to date with changes checked into the
master repository since you last checked out or updated
your files.
.TP
.I "To Check In Your Changes"
Use CVS
.BR commit
in a directory containing working files.
This command checks your changes into the master repository.
You can specify files by name or use
.XS
cvs commit \-a
.XE
to
.B commit
all the files you have changed.
.TP
.I "To Add a File"
Add the file to the working directory.
Use CVS
.B add
to mark the file as added.
Use CVS
.B commit
to add the file to the master repository.
.TP
.I "To Remove a File"
Remove the file from the working directory.
Use CVS
.B remove
to mark the file as removed.
Use CVS
.B commit
to move the file from its current location in the master repository
to the CVS
.IR Attic
directory.
.TP
.I "To Add a Directory"
Add the directory to the working directory.
Use CVS
.B add
to add the directory to the master repository.
.TP
.I "To Remove a Directory"
.br
You shouldn't remove directories under CVS. You should instead remove
their contents and then prune them (using the
.B \-f
and
.B \-p
options) when you
.B checkout
or
.B update
your working files.
.TP
.I "To Tag a Release"
Use CVS
.B tag
to apply a symbolic tag to the latest revision of each file in the
master repository. For example:
.XS
cvs tag V2_1 behemoth
.XE
.TP
.I "To Retrieve an Exact Copy of a Previous Release"
During a CVS
.B checkout
or
.BR update ,
use the
.B \-r
option to retrieve revisions associated with a symbolic tag.
Use the
.B \-f
option to ignore all RCS files that do not contain the
tag.
Use the
.B \-p
option to prune directories that wind up empty because none
of their files matched the tag. Example:
.XS
cd ~/work
cvs checkout \-r V2_1 \-f \-p behemoth
.XE
.SS "Logging Changes"
It is a good idea to keep a change log together with the
sources. As a minimum, the change log should name and describe each
tagged release. The change log should also be under CVS control and
should be tagged along with the sources.
.LP
.BR cvslog (local)
can help. This command logs
changes reported during CVS
.B commit
operations. It automatically
updates a change log file in your working directory. When you are
finished making changes, you (optionally) edit the change log file and
then commit it to the master repository.
.LP
Note: You must edit the change log to describe a new release
and
.B commit
it to the master repository
.I before
.BR tag ging
the release using CVS. Otherwise, the release description will not be
included in the tagged package.
.LP
See
.BR cvslog (local)
for more information.
.SS "Merging a Subsequent Third-Party Distribution"
The initial steps in this process are identical to placing a
third-party distribution under CVS for the first time: save the
distribution kit and unpack the package in a scratch directory. From
that point the steps diverge.
The following example considers release 5.0 of the
Bugs-R-Us package.
.TP
\(bu
Check in the sources after unpacking them:
.XS
cd ~/scratch
checkin \-m 'Bugs-R-Us 5.0 distribution' bugs VENDOR V5_0 \\
| tee ~/WARNINGS
.XE
It is important to save the output of
.B checkin
in a file
because it lists the sources that have been locally modified.
It is best to save the file in a different directory (for example,
your home directory). Otherwise,
.B checkin
will try to check it into the master repository.
.TP
\(bu
In your usual working directory, check out a fresh copy of the
distribution that you just checked in.
.XS
cd ~/work
cvs checkout \-r VENDOR bugs
.XE
The
.B checkout
command shown above retrieves the latest revision on the vendor branch.
.TP
\(bu
See the `WARNINGS' file for a list of all locally modified
sources.
For each locally modified source,
look at the differences between
the new distribution and the latest local revision:
.XS
cvs diff \-r \fR\fILocalRev file\fR\fB
.XE
In this command,
.I LocalRev
is the latest
numeric or symbolic revision
on the RCS trunk of
.IR file .
You can use CVS
.B log
to get the revision history.
.TP
\(bu
If your local modifications to a file have been incorporated into
the vendor's distribution, then you should reset the default RCS
branch for that file to the vendor branch. CVS doesn't provide a
mechanism to do this. You have to do it by hand in the master
repository:
.XS
rcs \-bVENDOR \fR\fIfile\fR\fB,v
.XE
.TP
\(bu
If your local modifications need to be merged with the
new distribution, use CVS
.B join
to do it:
.XS
cvs join \-r VENDOR \fR\fIfile\fR\fB
.XE
The resulting file will be placed in your working directory.
Edit it to resolve any overlaps.
.TP
\(bu
Test the merged package.
.TP
\(bu
Commit all modified files to the repository:
.XS
cvs commit \-a
.XE
.TP
\(bu
Tag the repository with a new local tag.
.SS "Applying Patches to Third-Party Sources"
Patches are handled in a manner very similar to complete
third-party distributions. This example considers patches applied to
Bugs-R-Us release 5.0.
.TP
\(bu
Save the patch files together with the distribution kit
to which they apply.
The patch file names should clearly indicate the patch
level.
.TP
\(bu
In a scratch directory, check out the last `clean' vendor copy \- the
highest revision on the vendor branch with
.IR "no local changes" :
.XS
cd ~/scratch
cvs checkout \-r VENDOR bugs
.XE
.TP
\(bu
Use
.BR patch (local)
to apply the patches. You should now have an image of the
vendor's software just as though you had received a complete,
new release.
.TP
\(bu
Proceed with the steps described for merging a subsequent third-party
distribution.
.TP
\(bu
Note: When you get to the step that requires you
to check out the new distribution after you have
checked it into the vendor branch, you should move to a different
directory. Do not attempt to
.B checkout
files in the directory in
which you applied the patches. If you do, CVS will try to merge the
changes that you made during patching with the version being checked
out and things will get very confusing. Instead,
go to a different directory (like your working directory) and
check out the files there.
.SS "Advice to Third-Party Source Hackers"
As you can see from the preceding sections, merging local changes
into third-party distributions remains difficult, and probably
always will. This fact suggests some guidelines:
.TP
\(bu
Minimize local changes.
.I Never
make stylistic changes.
Change makefiles only as much as needed for installation. Avoid
overhauling anything. Pray that the vendor does the same.
.TP
\(bu
Avoid renaming files or moving them around.
.TP
\(bu
Put independent, locally written files like help documents, local
tools, or man pages in a sub-directory called `local-additions'.
Locally written files that are linked into an existing executable
should be added right in with the vendor's sources (not in a
`local-additions' directory).
If, in the future,
the vendor distributes something
equivalent to your locally written files
you can CVS
.B remove
the files from the `local-additions' directory at that time.
.SH SEE ALSO
.BR cvs (local),
.BR checkin (local),
.BR cvslog (local),
.BR cvscheck (local)
.SH AUTHOR
Lowell Skoog
.br
Software Technology Group
.br
Technical Computing
|