/contrib/cvs/contrib/cvshelp.man
Unknown | 561 lines | 561 code | 0 blank | 0 comment | 0 complexity | d5dba182e52059d18d578cec4adeda4f MD5 | raw file
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