diff options
Diffstat (limited to 'contrib/cvs/contrib/cvshelp.man')
| -rw-r--r-- | contrib/cvs/contrib/cvshelp.man | 561 |
1 files changed, 0 insertions, 561 deletions
diff --git a/contrib/cvs/contrib/cvshelp.man b/contrib/cvs/contrib/cvshelp.man deleted file mode 100644 index b166af69528b..000000000000 --- a/contrib/cvs/contrib/cvshelp.man +++ /dev/null @@ -1,561 +0,0 @@ -.\" 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 |