.TH RCVS 1 "21 December 1993" .nf NAME RCVS - Remote extension of CVS (Concurrent Versions System) SYNOPSIS RCVS provides remote access to the source code managed by CVS. It replicates RCS ("*,v") files to remote site based upon user's request by using rdist. The clone directory on the remote site should be kept permanent to save the time it takes to replicate the modules. Only those modules requested by user will be replicated to the remote site. After the forward synchronization, RCVS executes the given CVS command on the remote site as usual. All operations are conducted upon the clone directory. If the command is 'commit', etc, a backward synchronization is conducted to replicate modules back to master site. There are number of options: -d cvsroot overrides $CVSROOT as the root of the CVS tree, it can be in either local or remote format. -t turn on cvs & rcvs trace -v display CVS version & rcvs version. -c change repository of a local folder by rewritting CVS/Repository according to revised CVSROOT. Use it with update or checkout commands. This can be used to force a local checkout with CVSROOT or convert a local folder when CVSROOT is changed. Note: Remote folder cannot be converted to local folder. -C Change repository of a remote folder by rewritting CVS/Remote according to revised CVSROOTr. Use this option when any components in CVSROOTr is changed. Use it with update or checkout command. This can be used to convert a remote folder when CVSROOTr is changed. (or for adding CVS/Remote to folders created by RCVS-0.3.9 or earlier version). Note: Local folder cannot be converted to remote folder. -R remote checkout according to $CVSROOTr, which must be in remote format. -P phases combination of steps to process remote folder [1-3] (careful!) 1: sync from root to clone. 2: run cvs in shell dealing with clone 3: sync back from clone to root. e.g. "cvs -P 2 his mod" -U Remove RCVS lock to recover from abnormal situation. Options used for internal usage: -L set lock for remote folder. -S Do sync. This is the first step in processing a remote folder. -e ver the RCVS version number of the client, borrow -e for internal use -X cvsrec the account which receives rdist data from server in phase 1. -Y tmpfile run local CVS command in shell. This is the second step in processing a remote folder. -Z convert rcvs-0.3.9 remote folder. choice 1. use single CVSROOT setenv CVSROOT user@host:repo:clone Where "user" is the login account on the server host. "host" is the network address of the server host. "repo" is the main repository on the server host. "clone" is the clone directory on current host. (Make sure there is no important files already in this directory). Optionally one can omit user@ to use the output of 'whoami'. This is probably the simplest and straight forward way to run CVS/rCVS, simply toggle CVSROOT between local and remote format. choice 2. use CVSROOT and CVSROOTr setenv CVSROOT cvsroot_directory setenv CVSROOTr user@host:root:clone Use option "-R" to do remote checkout according to CVSROOTr. Ignoring "-R" to do local checkout according to CVSROOT. Optionally setenv CVSMODE to "remote" or "local" to switch between CVSROOT and CVSROOTr. CVSROOT and/or CVSEROOTr are required by command such as checkout and import where no existing folders exists. rCVS evaluates CVSMODE, CVSROOT, and CVSROOTr to determine whether the repository resides locally or remotely. For any command working on existing folder, the repository of existing folder is used. Note: The memorized repository of Local folders must match current CVSROOT. Thus if you deal with both local and remote folder, you may want to use dual CVSROOT/CVSROOTr scheme. Selecting the clone: ~~~~~~~~~~~~~~~~~~~~ The clone is a temporary buffer which is a copy of the main repository. Group of user can use the same clone as long as they can access to it. Choose a directory that have ample space. Don't use the clone as local repository. One common mistake is setting the clone as $CVSROOT, hoping that one can use the clone locally to save time. The clone is just a working buffer, it should not be used as local repository! One must deal with the main repository directly, it takes more network access time, but that's the only way all activities can be synchronized globally. See later section "If network is too slow" if the network is too slow. Set up $HOME/.rhosts on both side of the network so that two accounts can rlogin to each other. A common way to set up sharable modules is 'chgrp -R' the directories in the main repository to the proper group name then 'chmod' them to 'drwxrwsr_x' (2775) with 'chmod -R g+ws'. (The 'g+s' turns on GID bit so that files created in a directory will carry the same group ID). The directories in the clone will be 'chmod'ed to the same symbolic (not numeric) group name by rCVS if this group name exists on local host. NOTE: when adding new directory in sharable module, remember to do 'chmod -R g+ws' on this new directory. CVS idenifies whether the working directory (a folder) is a remote folder or local folder by examine the existence of a file called CVS/Remote. The "Remote" file memorizes the user, server, repository, and clone of a remote folder. The format of CVS/Remote is: remote_repo rel_path remote_repo $_module Where remote_repo is in "user@host:cvsroot:clone" remote format and rel_path is the path of a repository relative to CVSROOT. If a module is defined explictly in CVSROOT/modules, then a prefix "$_" is added. Adding and Removing New Directories and Files: ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Use 'cvs add dirname' to add a directory into main repository. Then cd to dirname and use 'cvs add f1..' to add the name of all new files into CVS/Entries, finally use "cvs commit' to actually put them back into main repository. To save time, specify the file names for commit, e.g. "cvs commit f1 f2 ..". To remove a file, use 'rm' to remove file from disk, then do "cvs rm f1 f2.." to remove file from CVS/Entries, finally use 'cvs commit' to actually remove them from main repository. To save time, specify the file names for commit, e.g. "cvs commit f1 f2 ..". Scripts registerd in loginfo and modules ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The script registered in $CVSROOT/modules and $CVSROOT/loginfo will be executed in phase 2 against the clone on the remote host. This may cause problem if user's script is not installed on the remote host. Starting from rcvs-0.7.3, the script defined in loginfo will be executed on the server if the script is called loginfo.sh. For instance, if one entry in loginfo is 'mod1 /bin/loginfo.sh ...', then this line will be executed on server, use this feature if it deals with files external to the CVS repository, for instance, to make a reference copy on server. Simple test ~~~~~~~~~~~ Before running rcvs for the first time, try 'rsh server-machine -l username cvs -v' from remote machine to see if cvs is in the search path of server. Some user exit from their .cshrc if it is non- interactive C-Shell and never set up PATH properly. Next, try 'rsh server-machine -l username date' and 'rsh my-machine -l username date' to see if the profile writes any additional message to the stdout other than the date, if so turn them off from the profile (e.g. .cshrc). For HP/UX replace the 'rsh' with 'remsh', for SGI, replaced the 'rsh' with /usr/bsd/rsh in this simple test. Finally, test rdist with 'rdist -c $HOME/.cshrc username@same-machine:/tmp/junk' to make sure rdist works from itself. Then 'rdist -c $HOME/.cshrc username@server-machine:/tmp/junk' from your machine and 'rdist -c $HOME/.cshrc username@your-machine:/tmp/junk' from server machine to make sure rdist works between 2 machines. Rdist will give you error message: "version numbers don't match" if the login shell (.cshrc or .profile) generates message to the screen. If all test passed, you are ready to use rcvs! Ping Time ~~~~~~~~~ How fast is your network access between client and server? Try 'ping' to get a rough idea: the network access is fast if average 'ping' time is less than 100ms. The network access is medium if average 'ping' time is between 100 and 200ms. The network access is slow if the average 'ping' time is greater than 200ms. Try to use 'file-mode' by specifying individual files instead of whole module can speed up the process somewhat. If network is too slow ~~~~~~~~~~~~~~~~~~~~~~ If network speed is unbearable, try the following solution: put 'cvs -d user@server:main-repo:clone -P 1 co modulename' into /etc/crontab to do phase [1] automatically daily. Then set environment variable 'CVSBYPASS' to 1. The readonly operations like 'checkout' will bypass phase [1] and read from clone. At worst case user may be one day behind in getting the update. If you get 'module not up-to-date' message during 'cvs commit', type 'unsetenv CVSBYASS' followed by 'cvs update' to update from main repository directly. This feature is available in 0.8.1 and later versions. EXAMPLES option 1: setenv CVSROOT /my/cvsroot # set CVSROOT to local format cvs co gismo # local checkout from CVSROOT setenv CVSROOT terryh@owl.edu:/svr/cvsroot:/my/clone cvs co mod # remote checkout from CVSROOT option 2: setenv CVSROOT /client/cvsroot setenv CVSROOTr terryh@owl.com:/svr/cvsroot:/my/clone cvs co gismo # local checkout from CVSROOT cvs -R co mod # remote checkout from CVSROOTr cvs add newdir # add new directory cd newdir; cvs add f1 f2... # add new files from new directory rm f1 f2.. # remove files from disk cvs remove f1 f2.. # remove files from CVS/Entries cvs commit f1 f2.. # remove files from main repository cvs commit mod # commit a folder, local or remote kind cvs -c update gismo # change local repository, use CVSROOT cvs -C update mod ENVIRONMENT VARIABLES: CVSROOT default repository for local folder. CVSROOTr optional. Default repository for remote folder. CVSMODE optional. Set mode of CVS to "remote" or "local". CVSDOMAIN optional. Network domain of the local host, not including host name. This is the last resort for those who cannot get correct domain. CVSUSER optional. Set its value to the output of 'whoami'. This is the last resort for those who cannot get correct username. CVSBYPASS optional. Set this flag to bypass phase 1, then run a daily cron job to do 'cvs -P 1 co' to do phase 1 automatically. See previous section "if network is too slow" CVSREC optional. Specify an account to receive rdist data from server. If CVSREC is set on server account, it will be used to receive rdist for all client. If CVSREC is set on client account, it will be used to receive rdist. If both are set, the client's CVSREC will override the server's CVSREC. This variable can be used to emulate server-client model. FILES /tmp/RCVS/distfile.$user: a copy of distfile for debugging /tmp/RCVS/$username.$PID/$modules: a barebone directory tree on server. $root/CVSROOT/#rcvs.lock: rCVS lock, root can be $CVSROOT or clone. $clone/CVSROOT/#rcvsr.lock: rCVS read lock in clone directory $CVSROOT/CVSROOT/#rcvsX.lock: CVS lock to protect main repository $CVSROOT/CVSROOT/#rcvsXr.lock: CVS read lock to protect main repository $CVSROOT/dir: main repository clone/dir: clone repository .: working directory, folder ./CVS/Remote: data file to memorize the repository SEE ALSO cvs(1), cvs(5) A paper written by Paul Kunz is available from anonymous ftp server preprint.slac.stanford.edu, the file is pub/slacpubs/slac-pub-5923.ps.Z BUGS Rdist will give you error message: "version numbers don't match" if the login shell (.cshrc or .profile) generates message to the screen. You will get the following message: "ci error: Date ... is not later than or equal to ..." or other time-stamp problem if version 4 of RCS instead of version 5 is running on either local or remote host. Check RCS version with "strings /usr/local/bin/ci | grep ci.c", if the date you get is much earlier than 1991/11/20, you have RCS-4.