How to Use RCS Version control.

Contents:

Introduction

The RCS source control system is important to use when files may be edited by several individuals. Using the correct procedure insures the following:

1. that changes made are not lost.
2. that there is a log of modifications made This will allow you track why things were done is specific ways.
3. allow you to revert to older versions This is usually done because the current version may have errors or not applicable to a particular use.

It takes a very small time to use the RCS system. It will save you loads of time the first instance you have to refer to the log messages or have to revert to a previous version.

Please note: The phrase 'working file' mentioned in the following sections refers to a file in your working directory. This 'working file' will be edited, and checked in and out of the RCS system.

Please note: The phrase '<Enter>' indicates the operator should press the enter key on the keyboard to commit the entered command.

A) Before using the system make sure there is a RCS sub directory in your working directory.

mkdir RCS <Enter>

This command will create the sub directory 'RCS' in your current working directory. Saved versions of your checked in 'working file(s)' will be stored in this sub directory.

B) How to setup new file in the RCS system. (ci -u)

ci -u filename <Enter>

This command will initialize the RCS version file for the file 'filename'.

• The system will prompt '>>' you for a description of the file to be used as the initial description by RCS
• enter the multi-line description
• end the description by entering a '.' period on a line by itself.

This command will create a RCS archive of the specified file in the RCS subdirectory. It will leave the working file as-is but will set the permissions to read-only. This is to make it more difficult for people to accidently edit the file without checking the file out with the RCS system.

The first time you use the 'ci -u' command you will be asked to describe what the file contains or what it does (in the case of script files). This is NOT a change log message!

Note: Each subsequent use of 'ci -u' will add the changes to the RCS archive. The system will ask you for a log message detailing what has been changed. See 'ci' utility discussed in section (D.1) below for more information.

C) When you want to edit the file you should perform the following sequence prior to checking it out:

1. Run the 'rlog' utility to see if anyone has already checked out the file. If some one has checked out the file do the following
   • if they are editing the file wait for them to check the file back in before continuing.
   • if they forgot to check it back in ask them to check it in before you continue.
   • if you have to override the lock go to step (C.4)

   An example of the use of 'rlog':

   rlog -h filename <Enter>

   This will print a short discription of the RCS file including current version and locks.

   If you want the full log file (could be quite large):

   rlog filename <Enter>

   ---

   *** Note ***
   If there are alot of versions you might want to pipe the rlog results through the more utility. An example of its use:

   rlog filename | more <Enter>

   To quit the more command type a letter 'q'.

   ---

2. Run the 'rcsdiff' utility to insure some one wasn't tampering with the current working version. If rcsdiff says that there are differences then investigate before continuing. An example of its use:

   rcsdiff filename <Enter>

3. Now that file is ready to be checked out use the 'co' utility. An example of use follows:

   co -l filename <Enter>

   This command will check out the file named 'filename' and place a lock on it in the RCS system.

   You may now edit the file to your hearts content.

   Note: You should check the file in immediately after editing the file. That way you won't forget why you edited the file (this is important when checking the file. See checking in a file below).

   ---

   *** Important ***
   This command will overwrite any working file that may be in the working directory. REMEMBER you should NOT edit a working file unless you check it out and lock the file. If the working file is different than RCS version you have a problem. This means only one possibility: Some one altered the working file without checking it out

   ---

4. What should I do if I have to override the RCS lock?

   You should only override the RCS lock for the following reasons:

   • Some one checked out the file, didn't perform any editing on the file and are not available to unlock the file.
   • Some one edited the file and forgot to check it back in

   What you have to consider before overriding RCS locks.

   • You have to decide whether or not you are going to ignore the changes or incorporate the changes in your edit
   • If you are going to incorporate the changes perform an rcsdiff an note the changes before continuing.
   • overriding a locked unchanged working file OR overriding a locked changed working file that you want to DELETE the changes:

     rcs -u filename <Enter>

     This will unlock the file 'filename'. It will also send an email message to person who owned the previous lock.

     Now go to step (C.3) to check out the file.

   • overridng a locked and changed working file that you want to keep the changes.
     1. rcs -u filename <Enter>

        This will unlock the file 'filename'. It will also send an email message to person who owned the previous lock.

     2. ci -l filename <Enter>

        This will check in the file 'filename' Enter in the log the following information:

        1. That you overroade the lock by user: ????
        2. The changes that were made by that user and why.

           Note: This will also automatically check out the file in your name so you may perform your changes.

D) How to check a file into the RCS system. (ci)

1. Checking in an edited file that has previously been setup in the RCS system.

   ci -u filename <Enter>

   ---

   *** Important ***
   If you have not previously setup the file in the RCS system the ci utility will perform the 'rcs' function (see section (B)) before performing the check in operation. The description of the file will be requested instead of the log message request.

   ---

   • The system will ask you to enter a log of the changes that were made to the file.
   • enter the change log
   • end the log by entering a '.' period on a line by itself.

     Note: the '-u' option will leave a copy of the file in your working directory. If you do not use the '-u' option RCS will delete the working file after checking in the file.

   ---

   *** Important ***
   Since most of our working files are live files (ie., configuration files or html files) use the '-u' option.

   ---

2. Checking in a edited file that has a very long change log message.

   ci -m'cat log.txt' -u filename <Enter>

   This will check in the file as in (D.1) above but will get the log information from a previously create text file named 'log.txt'.

   Note: you can use the '-m' option with the '-l' option. See section (D.3) below.

3. Checking in intermediate changes and relocking the file to continue changes. This is an important tool to use if you are performing extensive changes to a file and you want to edit you file in stages. Incase you botch you changes ... you can recover from you last RCS checkin. See section (E) for direction concerning how to recover from previous versions.

   ci -l filename <Enter>

   This will check in the file 'filename' as with 'ci -u'. The only difference is that the file is immediately checked out and locked after being checked in.

4. Checking in an edited working file and removing the working file.

   ci filename <Enter>

   Note: This will delete the working file. This is normally only done when you don't want any working files hanging around.

   ---

   *** Warning ***
   Do not use this check in method on active working files like web files and software configuration files.

   ---

E) How to recover from a previous saved RCS version of a file.

1. Recovering from the most current version of the file.

   ---

   *** Warning ***
   Do not perform this if some one else has the file locked See section (C.4) form more information.

   ---

   1. rcs -u filename <Enter>

      This will turn off the lock on the file 'filename'

      ---

      *** Warning ***
      The following command will overwrite your current working file. So if there is any information in that working file that you want to keep copy it to another file (under a new file name).

      ---

   2. co -l filename <Enter>

      This will check out and lock the current version of the file 'filename'. The current working file will be overwritten.

2. Recovering from a specific saved RCS version.

   1. rcs -u filename <Enter>

      This will turn off the lock on the file 'filename'

      ---

      *** Warning ***
      The following command will overwrite your current working file. So if there is any information in that working file that you want to keep copy it to another file (under a new file name).

      ---

   2. co -r1.3 -l filename <Enter>

      This will check out and lock version 1.3 of the file 'filename'. The current working file will be overwritten.

F) How to refresh a currently unlocked working file. (co -u)

co -u filename <Enter>

This will insure the working file is the same as the current saved version in the RCS system.

G) How to view differences between different RCS versions (rcsdiff)

You can see the differences between different versions of an RCS file.

rcsdiff -r1.5 -r1.3 filename <Enter>

This will compare the two versions of the RCS file 'filename'. It will print the difference list to your terminal.

The following command will compare the current working file to the most recent RCS saved version:

rcsdiff filename <Enter>

The following command will compare the current working file to the specific RCS saved version:

rcsdiff -r1.3 filename <Enter>

rcsdiff filename | more <Enter>

H) How to recover from editing an Unlocked readonly working file.

Occasionally you might start editing an unlocked working file that is in read only mode. This means you cannot save your changes to the working file. A recovery procedure follows:

1. Save the contents of your edit buffer to a temporary file.
2. Close out of your editor leaving the working file unchanged.
3. You have to check the RCS system to see if the working file is currently locked. (see section C.1).
4. Check the difference between the the most current saved RCS version and the current working file. (see section C.2).
   1. The RCS version and the working file are DIFFERENT.
      You have to decide whether or not you want to keep the changes of the current working file.
      1. Yes. You want to keep the working file changes.
         • Checkout and lock the file (co -l filename).
         • Copy the temporary file to the working file.
         • Checkin the working file (ci -u filename).
      2. No. You do NOT want to keep the working file changes.
         • You should do a difference check between the temporary file and the working file. This will show you the changes that you have made to the working file. (diff tempfile workfile).
         • Checkout and lock the file (co -l filename).
           This procedure is destructive to the working file. This will overwrite the current working file with the most recent RCS version.
         • Apply the changes determined in the difference check.
         • Checkin the working file (ci -u filename).
   2. The RCS version and the working file are the SAME.
      • Checkout and lock the file (co -l filename).
        This procedure is destructive to the working file. This will overwrite the current working file with the most recent RCS version. This should be okay. Since you have already determined that the current RCS version is the same as the working file.
      • Copy the contents of the temporary file into the working file.
      • Checkin the working file (ci -u filename).

webunit@athabascau.ca
This page was last modified on March 30, 1999 by E. Ady.