• merge latest version of rannotate code from corecode
[alioth/cvs.git] / contrib / cvshelp.man
1 .\" Contributed by Lowell Skoog <fluke!lowell@uunet.uu.net>
2 .\" Full space in nroff; half space in troff
3 .de SP
4 .if n .sp
5 .if t .sp .5
6 ..
7 .\" Start a command example
8 .de XS
9 .SP
10 .in +.5i
11 .ft B
12 .nf
13 ..
14 .\" End a command example
15 .de XE
16 .fi
17 .ft P
18 .in -.5i
19 .SP
20 ..
21 .TH CVSHELP LOCAL "17 March 1991" FLUKE
22 .SH NAME 
23 cvshelp \- advice on using the Concurrent Versions System
24 .SH DESCRIPTION
25 This man page is based on experience using CVS.
26 It is bound to change as we gain more experience.
27 If you come up with better advice than is found here,
28 contact the Software Technology
29 Group and we will add it to this page.
30 .SS "Getting Started"
31 Use the following steps to prepare to use CVS:
32 .TP
33 \(bu
34 Take a look at the CVS manual page to see what it can do for you, and
35 if it fits your environment (or can possibly be made to fit your
36 environment).
37 .XS
38 man cvs
39 .XE
40 If things look good, continue on...
41 .TP
42 \(bu
43 Setup the master source repository.  Choose a directory with
44 ample disk space available for source files.  This is where the RCS
45 `,v' files will be stored.  Say you choose 
46 .B /src/master
47 as the root
48 of your source repository.  Make the 
49 .SB CVSROOT.adm 
50 directory in the root of the source repository:
51 .XS
52 mkdir /src/master/CVSROOT.adm
53 .XE
54 .TP
55 \(bu
56 Populate this directory with the
57 .I loginfo
58 and
59 .I modules
60 files from the
61 .B "/usr/doc/local/cvs"
62 directory.  Edit these files to reflect your local source repository
63 environment \- they may be quite small initially, but will grow as
64 sources are added to your source repository.  Turn these files into
65 RCS controlled files:
66 .XS
67 cd /src/master/CVSROOT.adm
68 ci \-m'Initial loginfo file' loginfo
69 ci \-m'Initial modules file' modules
70 .XE
71 .TP
72 \(bu
73 Run the command:
74 .XS
75 mkmodules /src/master/CVSROOT.adm
76 .XE
77 This will build the 
78 .BR ndbm (3)
79 file for the modules database.
80 .TP
81 \(bu
82 Remember to edit the 
83 .I modules 
84 file manually when sources are checked
85 in with 
86 .B checkin
87 or CVS
88 .BR add .
89 A copy of the 
90 .I modules 
91 file for editing can be retrieved with the command:
92 .XS
93 cvs checkout CVSROOT.adm
94 .XE
95 .TP
96 \(bu
97 Have all users of the CVS system set the 
98 .SM CVSROOT 
99 environment variable appropriately to reflect the placement of your
100 source repository.  If the above example is used, the following
101 commands can be placed in a
102 .I .login 
103 or 
104 .I .profile 
105 file:
106 .XS
107 setenv CVSROOT /src/master
108 .XE
109 for csh users, and
110 .XS
111 CVSROOT=/src/master; export CVSROOT
112 .XE
113 for sh users.
114 .SS "Placing Locally Written Sources Under CVS Control"
115 Say you want to place the `whizbang' sources under
116 CVS control.  Say further that the sources have never 
117 been under revision control before.
118 .TP
119 \(bu
120 Move the source hierarchy (lock, stock, and barrel) 
121 into the master source repository:
122 .XS
123 mv ~/whizbang $CVSROOT
124 .XE
125 .TP
126 \(bu
127 Clean out unwanted object files:
128 .XS
129 cd $CVSROOT/whizbang
130 make clean
131 .XE
132 .TP
133 \(bu
134 Turn every file in the hierarchy into an RCS controlled file:
135 .XS
136 descend \-f 'ci \-t/dev/null \-m"Placed under CVS control" \-nV\fR\fIx\fR\fB_\fR\fIy\fR\fB *'
137 .XE
138 In this example, the initial release tag is \fBV\fIx\fB_\fIy\fR,
139 representing version \fIx\fR.\fIy\fR.
140 .LP
141 You can use CVS on sources that are already under RCS control.
142 The following example shows how.  
143 In this example, the source package is called `skunkworks'.
144 .TP
145 \(bu
146 Move the source hierarchy into the master source
147 repository:
148 .XS
149 mv ~/skunkworks $CVSROOT
150 .XE
151 .TP
152 \(bu
153 Clean out unwanted object files:
154 .XS
155 cd $CVSROOT/skunkworks
156 make clean
157 .XE
158 .TP
159 \(bu
160 Clean out unwanted working files, leaving only the RCS `,v' files:
161 .XS
162 descend \-r rcsclean
163 .XE
164 Note: If any working files have been checked out and changed,
165 .B rcsclean
166 will fail.  Check in the modified working files 
167 and run the command again.
168 .TP
169 \(bu
170 Get rid of 
171 .SB RCS 
172 subdirectories.  CVS does not use them.
173 .XS
174 descend \-r \-f 'mv RCS/*,v .'
175 descend \-r \-f 'rmdir RCS'
176 .XE
177 .TP
178 \(bu
179 Delete any unwanted files that remain in the source hierarchy.  Then
180 make sure all files are under RCS control:
181 .XS
182 descend \-f 'ci \-t/dev/null \-m"Placed under CVS control" \-n\fR\fItag\fR\fB *'
183 .XE
184 .I tag
185 is the latest symbolic revision tag that you applied to your package
186 (if any).  Note:  This command will probably generate lots of error
187 messages (for directories and existing RCS files) that you can
188 ignore.
189 .SS "Placing a Third-Party Source Distribution Under CVS Control"
190 The 
191 .B checkin
192 command checks third-party sources into CVS.  The 
193 difference between third-party sources and locally
194 written sources is that third-party sources must be checked into a
195 separate branch (called the
196 .IR "vendor branch" )
197 of the RCS tree.  This makes it possible to merge local changes to
198 the sources with later releases from the vendor.
199 .TP
200 \(bu
201 Save the original distribution kit somewhere.  For example, if the
202 master source repository is
203 .B /src/master
204 the distribution kit could be saved in
205 .BR /src/dist .
206 Organize the distribution directory so that each release 
207 is clearly identifiable.
208 .TP
209 \(bu
210 Unpack the package in a scratch directory, for example
211 .BR ~/scratch .
212 .TP
213 \(bu
214 Create a repository for the package.
215 In this example, the package is called `Bugs-R-Us 4.3'.  
216 .XS
217 mkdir $CVSROOT/bugs
218 .XE
219 .TP
220 \(bu
221 Check in the unpacked files:
222 .XS
223 cd ~/scratch
224 checkin \-m 'Bugs-R-Us 4.3 distribution' bugs VENDOR V4_3
225 .XE
226 There is nothing magic about the tag `VENDOR', which is applied to
227 the vendor branch.  You can use whatever tag you want.  `VENDOR' is a
228 useful convention.
229 .TP
230 \(bu
231 Never modify vendor files before checking them in.
232 Check in the files
233 .I exactly
234 as you unpacked them.
235 If you check in locally modified files, future vendor releases may
236 wipe out your local changes.
237 .SS "Working With CVS-Controlled Sources"
238 To use or edit the sources, you must check out a private copy.
239 For the following examples, the master files are assumed to reside in 
240 .BR "$CVSROOT/behemoth" .
241 The working directory is
242 .BR "~/work" .
243 See
244 .BR cvs (local) 
245 for more details on the commands mentioned below.
246 .TP
247 .I "To Check Out Working Files
248 Use CVS
249 .BR checkout :
250 .XS
251 cd ~/work
252 cvs checkout behemoth
253 .XE
254 There is nothing magic about the working directory.  CVS will check
255 out sources anywhere you like.  Once you have a working copy of the
256 sources, you can compile or edit them as desired.
257 .TP
258 .I "To Display Changes You Have Made"
259 Use CVS
260 .BR diff 
261 to display detailed changes, equivalent to
262 .BR rcsdiff (local).
263 You can also use
264 .BR cvscheck (local)
265 to list files added, changed, and removed in
266 the directory, but not yet 
267 .BR commit ted.
268 You must be in a directory containing working files.
269 .TP
270 .I "To Display Revision Information"
271 Use CVS
272 .BR log ,
273 which is equivalent to
274 .BR rlog (local).
275 You must be in a directory containing working files.
276 .TP
277 .I "To Update Working Files"
278 Use CVS
279 .BR update 
280 in a directory containing working files.
281 This command brings your working files up 
282 to date with changes checked into the
283 master repository since you last checked out or updated
284 your files.
285 .TP
286 .I "To Check In Your Changes"
287 Use CVS
288 .BR commit 
289 in a directory containing working files.
290 This command checks your changes into the master repository.
291 You can specify files by name or use 
292 .XS
293 cvs commit \-a
294 .XE
295 to
296 .B commit
297 all the files you have changed.
298 .TP
299 .I "To Add a File"
300 Add the file to the working directory.
301 Use CVS
302 .B add
303 to mark the file as added.
304 Use CVS
305 .B commit
306 to add the file to the master repository.
307 .TP
308 .I "To Remove a File"
309 Remove the file from the working directory.
310 Use CVS
311 .B remove
312 to mark the file as removed.
313 Use CVS
314 .B commit
315 to move the file from its current location in the master repository 
316 to the CVS
317 .IR Attic 
318 directory.
319 .TP
320 .I "To Add a Directory"
321 Add the directory to the working directory.
322 Use CVS
323 .B add
324 to add the directory to the master repository.
325 .TP
326 .I "To Remove a Directory"
327 .br
328 You shouldn't remove directories under CVS.  You should instead remove
329 their contents and then prune them (using the
330 .B \-f
331 and 
332 .B \-p
333 options) when you 
334 .B checkout 
335 or 
336 .B update 
337 your working files.
338 .TP
339 .I "To Tag a Release"
340 Use CVS
341 .B tag
342 to apply a symbolic tag to the latest revision of each file in the
343 master repository.  For example:
344 .XS
345 cvs tag V2_1 behemoth
346 .XE
347 .TP
348 .I "To Retrieve an Exact Copy of a Previous Release"
349 During a CVS
350 .B checkout
351 or
352 .BR update ,
353 use the 
354 .B \-r
355 option to retrieve revisions associated with a symbolic tag.
356 Use the
357 .B \-f
358 option to ignore all RCS files that do not contain the
359 tag.
360 Use the
361 .B \-p
362 option to prune directories that wind up empty because none
363 of their files matched the tag.  Example:
364 .XS
365 cd ~/work
366 cvs checkout \-r V2_1 \-f \-p behemoth
367 .XE
368 .SS "Logging Changes"
369 It is a good idea to keep a change log together with the
370 sources.  As a minimum, the change log should name and describe each
371 tagged release.  The change log should also be under CVS control and
372 should be tagged along with the sources.
373 .LP
374 .BR cvslog (local)
375 can help.  This command logs
376 changes reported during CVS 
377 .B commit 
378 operations.  It automatically
379 updates a change log file in your working directory.  When you are
380 finished making changes, you (optionally) edit the change log file and
381 then commit it to the master repository.
382 .LP
383 Note: You must edit the change log to describe a new release
384 and 
385 .B commit
386 it to the master repository
387 .I before
388 .BR tag ging
389 the release using CVS.  Otherwise, the release description will not be
390 included in the tagged package.
391 .LP
392 See
393 .BR cvslog (local)
394 for more information.
395 .SS "Merging a Subsequent Third-Party Distribution"
396 The initial steps in this process are identical to placing a
397 third-party distribution under CVS for the first time: save the
398 distribution kit and unpack the package in a scratch directory.  From
399 that point the steps diverge.
400 The following example considers release 5.0 of the
401 Bugs-R-Us package.
402 .TP
403 \(bu
404 Check in the sources after unpacking them:
405 .XS
406 cd ~/scratch
407 checkin \-m 'Bugs-R-Us 5.0 distribution' bugs VENDOR V5_0 \\
408         | tee ~/WARNINGS
409 .XE
410 It is important to save the output of 
411 .B checkin
412 in a file
413 because it lists the sources that have been locally modified.
414 It is best to save the file in a different directory (for example,
415 your home directory).  Otherwise, 
416 .B checkin 
417 will try to check it into the master repository.
418 .TP
419 \(bu
420 In your usual working directory, check out a fresh copy of the
421 distribution that you just checked in.
422 .XS
423 cd ~/work
424 cvs checkout \-r VENDOR bugs
425 .XE
426 The
427 .B checkout
428 command shown above retrieves the latest revision on the vendor branch.
429 .TP
430 \(bu
431 See the `WARNINGS' file for a list of all locally modified
432 sources.
433 For each locally modified source,
434 look at the differences between 
435 the new distribution and the latest local revision:
436 .XS
437 cvs diff \-r \fR\fILocalRev file\fR\fB
438 .XE
439 In this command,
440 .I LocalRev 
441 is the latest 
442 numeric or symbolic revision 
443 on the RCS trunk of
444 .IR file .
445 You can use CVS
446 .B log
447 to get the revision history.
448 .TP
449 \(bu
450 If your local modifications to a file have been incorporated into
451 the vendor's distribution, then you should reset the default RCS
452 branch for that file to the vendor branch.  CVS doesn't provide a
453 mechanism to do this.  You have to do it by hand in the master
454 repository:
455 .XS
456 rcs \-bVENDOR \fR\fIfile\fR\fB,v
457 .XE
458 .TP
459 \(bu
460 If your local modifications need to be merged with the 
461 new distribution, use CVS
462 .B join
463 to do it:
464 .XS
465 cvs join \-r VENDOR \fR\fIfile\fR\fB
466 .XE
467 The resulting file will be placed in your working directory.
468 Edit it to resolve any overlaps.
469 .TP
470 \(bu
471 Test the merged package.
472 .TP
473 \(bu
474 Commit all modified files to the repository:
475 .XS
476 cvs commit \-a
477 .XE
478 .TP
479 \(bu
480 Tag the repository with a new local tag.
481 .SS "Applying Patches to Third-Party Sources"
482 Patches are handled in a manner very similar to complete
483 third-party distributions.  This example considers patches applied to
484 Bugs-R-Us release 5.0.
485 .TP
486 \(bu
487 Save the patch files together with the distribution kit 
488 to which they apply.  
489 The patch file names should clearly indicate the patch
490 level.
491 .TP
492 \(bu
493 In a scratch directory, check out the last `clean' vendor copy \- the
494 highest revision on the vendor branch with 
495 .IR "no local changes" :
496 .XS
497 cd ~/scratch
498 cvs checkout \-r VENDOR bugs
499 .XE
500 .TP
501 \(bu
502 Use 
503 .BR patch (local)
504 to apply the patches.  You should now have an image of the 
505 vendor's software just as though you had received a complete,
506 new release.
507 .TP
508 \(bu
509 Proceed with the steps described for merging a subsequent third-party
510 distribution.
511 .TP
512 \(bu
513 Note: When you get to the step that requires you
514 to check out the new distribution after you have
515 checked it into the vendor branch, you should move to a different
516 directory.  Do not attempt to 
517 .B checkout 
518 files in the directory in
519 which you applied the patches.  If you do, CVS will try to merge the
520 changes that you made during patching with the version being checked
521 out and things will get very confusing.  Instead, 
522 go to a different directory (like your working directory) and
523 check out the files there.
524 .SS "Advice to Third-Party Source Hackers"
525 As you can see from the preceding sections, merging local changes
526 into third-party distributions remains difficult, and probably
527 always will.  This fact suggests some guidelines:
528 .TP
529 \(bu
530 Minimize local changes.  
531 .I Never
532 make stylistic changes.
533 Change makefiles only as much as needed for installation.  Avoid
534 overhauling anything.  Pray that the vendor does the same.
535 .TP
536 \(bu
537 Avoid renaming files or moving them around.
538 .TP
539 \(bu
540 Put independent, locally written files like help documents, local
541 tools, or man pages in a sub-directory called `local-additions'.
542 Locally written files that are linked into an existing executable 
543 should be added right in with the vendor's sources (not in a
544 `local-additions' directory).
545 If, in the future,
546 the vendor distributes something
547 equivalent to your locally written files 
548 you can CVS
549 .B remove
550 the files from the `local-additions' directory at that time.
551 .SH SEE ALSO
552 .BR cvs (local),
553 .BR checkin (local),
554 .BR cvslog (local),
555 .BR cvscheck (local)
556 .SH AUTHOR
557 Lowell Skoog
558 .br
559 Software Technology Group
560 .br
561 Technical Computing