Using the RCS system

NOTE: This section is mainly for use by the main VMD developers, which use RCS to maintain the source code, documentation, and other files. The standard VMD ftp distribution does not include the RCS directory, and the discussions in the manual about RCS do not apply to that case. If you are NOT using RCS, you may simply skip this section and other pertaining to the use RCS when working on VMD.

The Revision Control System (RCS) is used here to allow several people to simultaneously work on modifications to the files used in compiling and running VMD. To do this, each file (i.e., source code files, utility scripts, data or documentation files) is stored in a special RCS format within the directory RCS in the main VMD working directory. Within each subdirectory, a link to this main RCS directory is made, so that there is one single official RCS dir, and several links to it. To obtain a copy of a file, a user checks out the file from RCS. If the file is to be changed, the user must also lock the file when checking it out. When the modifications are complete and verified to be successful, the same user checks the file back in, releasing the lock and depositing the changed version back in the main RCS directory. No other user can lock a file locked by another user until the lock has been released, thus guaranteeing that no two users are attempting to make conflicting changes to the same file simultaneously. Each time a file is modified and checked back in, the current version number of that file is increased; through RCS commands, older versions of a file may be retrieved if new changes end up not working out or are not needed. Several utility programs comprise the RCS system; this section describes the basic use of these programs to perform the tasks mentioned above.

• To add new files to the RCS:
  The rcs program is used to initialize new files, and the ci program checks in a new version. The commands to use are:

  rcs -i -a<username>[,<username>[...]] -L <new files>
  ci -u <new files>

  Each file in the RCS should have a special header which includes special commands to allow RCS to indicate the name, version, and other data in each file when it is checked out; see section 16.3 for notes on what RCS headers to use for each type of file (Latex, shell script, C/C++ source) and where to find standard RCS header examples.

• To check files out of the RCS:
  The co program retrieves files from the RCS directory, and puts the retrieved copy in the current directory. There are two ways to use this, the first to simply retrieve a copy of the file for read-only access, and the second to check out and lock a file, assuring you are the only one allowed to modify the file. The two commands are, respectively,

  co <list of files>
  co -l <list of files>

  For locked files, when modifications are complete the file should be checked back in, as described next. Files checked out, but not locked, do not need to be checked in.

• To check a file back into the RCS:
  The ci program updates the official RCS directory with a new version of a file previously checked out and locked by a user. When the file is checked in, its current version number is incremented, and the user may enter a quick note about what changes were made. It is possible to have these revision notes placed within the file itself as comments, and this is done by VMD through proper use of RCS headers. The command to check in a file is:

  ci -u <list of checked out files>

  The -u flag then does an automatic co <files> command, which assures there is a (non-locked) version of the file still in your directory after checking in a file.

• To unlock a file that has been locked, without checking it in:
  Occasionally changes are made to a file that has been locked out, but the changes are not needed or just plain don't work. To simply release a lock, which abandons the changes and in fact will completely erase them unless a copy is made by hand beforehand, use the commands:

  rcs -u <file>
  chmod -w <file>
  co <file>

  The first command releases the lock; the others reset the file and check out a copy of the old version (as it existed when initially checked out and locked).

Information on these RCS programs should be available via man pages as well.