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