1 .\" Contributed by Lowell Skoog <fluke!lowell@uunet.uu.net>
2 .\" Full space in nroff; half space in troff
7 .\" Start a command example
14 .\" End a command example
21 .TH CVSHELP LOCAL "17 March 1991" FLUKE
23 cvshelp \- advice on using the Concurrent Versions System
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.
31 Use the following steps to prepare to use CVS:
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
40 If things look good, continue on...
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
48 of your source repository. Make the
50 directory in the root of the source repository:
52 mkdir /src/master/CVSROOT.adm
56 Populate this directory with 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
67 cd /src/master/CVSROOT.adm
68 ci \-m'Initial loginfo file' loginfo
69 ci \-m'Initial modules file' modules
75 mkmodules /src/master/CVSROOT.adm
79 file for the modules database.
84 file manually when sources are checked
91 file for editing can be retrieved with the command:
93 cvs checkout CVSROOT.adm
97 Have all users of the CVS system set the
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
107 setenv CVSROOT /src/master
111 CVSROOT=/src/master; export CVSROOT
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.
120 Move the source hierarchy (lock, stock, and barrel)
121 into the master source repository:
123 mv ~/whizbang $CVSROOT
127 Clean out unwanted object files:
134 Turn every file in the hierarchy into an RCS controlled file:
136 descend \-f 'ci \-t/dev/null \-m"Placed under CVS control" \-nV\fR\fIx\fR\fB_\fR\fIy\fR\fB *'
138 In this example, the initial release tag is \fBV\fIx\fB_\fIy\fR,
139 representing version \fIx\fR.\fIy\fR.
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'.
146 Move the source hierarchy into the master source
149 mv ~/skunkworks $CVSROOT
153 Clean out unwanted object files:
155 cd $CVSROOT/skunkworks
160 Clean out unwanted working files, leaving only the RCS `,v' files:
164 Note: If any working files have been checked out and changed,
166 will fail. Check in the modified working files
167 and run the command again.
172 subdirectories. CVS does not use them.
174 descend \-r \-f 'mv RCS/*,v .'
175 descend \-r \-f 'rmdir RCS'
179 Delete any unwanted files that remain in the source hierarchy. Then
180 make sure all files are under RCS control:
182 descend \-f 'ci \-t/dev/null \-m"Placed under CVS control" \-n\fR\fItag\fR\fB *'
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
189 .SS "Placing a Third-Party Source Distribution Under CVS Control"
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.
201 Save the original distribution kit somewhere. For example, if the
202 master source repository is
204 the distribution kit could be saved in
206 Organize the distribution directory so that each release
207 is clearly identifiable.
210 Unpack the package in a scratch directory, for example
214 Create a repository for the package.
215 In this example, the package is called `Bugs-R-Us 4.3'.
221 Check in the unpacked files:
224 checkin \-m 'Bugs-R-Us 4.3 distribution' bugs VENDOR V4_3
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
231 Never modify vendor files before checking them in.
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
245 for more details on the commands mentioned below.
247 .I "To Check Out Working Files
252 cvs checkout behemoth
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.
258 .I "To Display Changes You Have Made"
261 to display detailed changes, equivalent to
265 to list files added, changed, and removed in
266 the directory, but not yet
268 You must be in a directory containing working files.
270 .I "To Display Revision Information"
273 which is equivalent to
275 You must be in a directory containing working files.
277 .I "To Update Working Files"
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
286 .I "To Check In Your Changes"
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
297 all the files you have changed.
300 Add the file to the working directory.
303 to mark the file as added.
306 to add the file to the master repository.
308 .I "To Remove a File"
309 Remove the file from the working directory.
312 to mark the file as removed.
315 to move the file from its current location in the master repository
320 .I "To Add a Directory"
321 Add the directory to the working directory.
324 to add the directory to the master repository.
326 .I "To Remove a Directory"
328 You shouldn't remove directories under CVS. You should instead remove
329 their contents and then prune them (using the
339 .I "To Tag a Release"
342 to apply a symbolic tag to the latest revision of each file in the
343 master repository. For example:
345 cvs tag V2_1 behemoth
348 .I "To Retrieve an Exact Copy of a Previous Release"
355 option to retrieve revisions associated with a symbolic tag.
358 option to ignore all RCS files that do not contain the
362 option to prune directories that wind up empty because none
363 of their files matched the tag. Example:
366 cvs checkout \-r V2_1 \-f \-p behemoth
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.
375 can help. This command logs
376 changes reported during CVS
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.
383 Note: You must edit the change log to describe a new release
386 it to the master repository
389 the release using CVS. Otherwise, the release description will not be
390 included in the tagged package.
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
404 Check in the sources after unpacking them:
407 checkin \-m 'Bugs-R-Us 5.0 distribution' bugs VENDOR V5_0 \\
410 It is important to save the output of
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,
417 will try to check it into the master repository.
420 In your usual working directory, check out a fresh copy of the
421 distribution that you just checked in.
424 cvs checkout \-r VENDOR bugs
428 command shown above retrieves the latest revision on the vendor branch.
431 See the `WARNINGS' file for a list of all locally modified
433 For each locally modified source,
434 look at the differences between
435 the new distribution and the latest local revision:
437 cvs diff \-r \fR\fILocalRev file\fR\fB
442 numeric or symbolic revision
447 to get the revision history.
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
456 rcs \-bVENDOR \fR\fIfile\fR\fB,v
460 If your local modifications need to be merged with the
461 new distribution, use CVS
465 cvs join \-r VENDOR \fR\fIfile\fR\fB
467 The resulting file will be placed in your working directory.
468 Edit it to resolve any overlaps.
471 Test the merged package.
474 Commit all modified files to the repository:
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.
487 Save the patch files together with the distribution kit
489 The patch file names should clearly indicate the patch
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" :
498 cvs checkout \-r VENDOR bugs
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,
509 Proceed with the steps described for merging a subsequent third-party
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
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:
530 Minimize local changes.
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.
537 Avoid renaming files or moving them around.
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).
546 the vendor distributes something
547 equivalent to your locally written files
550 the files from the `local-additions' directory at that time.
559 Software Technology Group
projects / dragonfly.git / blob