HMC Homepage CS Home

RCS: The Revision Control System

What Is RCS?

Using RCS More Information About RCS

What Is RCS?

RCS is the Revision Control System for managing multiple revisions of files. Muddcs staff keeps important system files under RCS for the following reasons:

  1. RCS attempts to prevent two people from editing the same file simultaneously.
  2. RCS keeps old copies of a file.
  3. A log of changes to a file can be kept.
MENU

Using RCS

RCS works with two kinds of files. The first is the working file, or regular file. The second is an RCS file, which is a compilation of all the differences between various revisions of a file. The working file is the one you would view or edit. If your file is named FILE, the RCS file is named FILE,v (by default).

The two most important RCS commands are ci, "check in", and co, "check out". ci puts a file under RCS and removes the working file, unless the -u flag (or certain others) is used. co gives you the working file back.

Initial Check In

Initial "check in" creates an RCS file. Here is a sample "check in" procedure for a file named FILE.

  1. Create a directory called RCS in the parent directory of your file. (RCS files don't have to be in a RCS directory, but this is usually the most convenient place for them, and this is where RCS looks for RCS files by default.)

  2. Put RCS keywords in the comments of your file. (These provide various information about the file. They are optional, but very useful.)

  3. Do an initial "check in" of your file.

    % ci -i -u FILE

    The -i flag tells RCS to check if FILE,v already exists, and the -u flag tells RCS to leave a non-writeable copy of the working file where the working file used to be.

If nothing else in the directory has been checked in to RCS, you will probably want to create a subdirectory named RCS, using the mkdir command. If such a directory exists, the RCS files will be located there, by default; otherwise, they are put in the current directory (unless you tell RCS otherwise). In addition, if there are others who will be editing the files, both the directory in which the files are located and the RCS directory should have the setgid bit set with the chmod g+s command, so that the files in the directory get its group by default (rather than yours), which (especially for the infosys pages) makes rcs happy.
MENU

Keywords

These two useful keywords should be put in comments in a file for identification purposes. If a file cannot be commented, DON'T put in keywords. RCS automatically generates information inserted after a keyword.

$Header: $
A standard header containing the full pathname of the RCS file, the revision number, the date and time, the author, the state, and the locker (if locked).
$Log: $
Like the $Header: $ keyword, but with the log messages RCS prompts for after an edit.
To see what keywords are in a file named FILE, type:

% ident FILE

Here are typical results.


  $Header: /mnt/web/www/qref/RCS/rcs.html,v 1.12 2003/01/27 23:17:54 ben Exp $
  $Log: rcs.html,v $
  Revision 1.12  2003/01/27 23:17:54  ben
  fixed the reference to CVS.

  Revision 1.11  2001/05/23 16:37:13  ben
  fixed footer

  Revision 1.10  2001/05/18 00:38:24  tim

  removed unnecessary section (concerning what system files to RCS) and fixed another formatting problem.

  Revision 1.9  2001/05/18 00:36:04  tim
  fixed some formatting issues.

  Revision 1.8  2001/01/04 05:45:34  nick
  ssi change
  ,

  Revision 1.7  2000/06/18 19:39:36  nhertl
  made it ssi style

  Revision 1.6  2000/06/05 21:34:46  aschoonm
  A few _more_ minor edits...

  Revision 1.5  2000/06/05 21:28:50  aschoonm
  A few more minor edits.

  Revision 1.4  2000/06/03 00:51:26  aschoonm


  Added some info on making an RCS directory and setting the setgid bit so as to facilitate use by other people.

  Revision 1.3  2000/04/21 16:43:24  nhertl
  formating

  Revision 1.2  2000/04/18 19:57:21  dbeutel
  *** empty log message ***

  Revision 1.1  1999/11/15 23:35:48  tim
  Initial revision

  

  To see the log of a file named FILE, you must type:
  

% rlog FILE

or
  

% rcs2log FILE


  There are many other keywords.  For a full list, read the man page
  ident(1).
  

MENU
  


  
Editing Files Under RCS

  To edit a file named FILE, follow these steps:


  	
    
	
  1. Check out the file and lock it with -l.  This gives write
	priveleges to you only.  Of course, this won't stop root from
	editing the file.  See the mistakes 
	section.

    
	% co -l FILE

    
	
  2. Edit the file.

    
	
  3. Check in the file, and leave a readable, but not writeable,
	copy of it.

    
	% ci -u FILE

    
  	


  Do not edit hardlinked files.


  MENU
  


  
Viewing Previous Versions of a File

  RCS keeps track of all revisions of a file.  You can view a previous
  version, say version 1.6, of a file (named FILE) by checking out the 
  old version and redirecting it to standard output.


  % co -p -r1.6 FILE


  You can see the differences between revisions with the rcsdiff
  command.  This example shows the differences between version 1.3 and
  1.6.


  % rcsdiff -r1.3 -r1.6


  MENU
  


  
Mistakes To Avoid

  	
    
	
  • Editing as Root Without Check Out
    
	Even if a file is RCS'd and non-writeable, root can still 
	edit it, without check out or check in.  If this happens,
	RCS will not be aware of the change in the file.  Next time
	this file is checked out, the revisions will be written 
	over with an old version of the file.  
	See Editing Files Under RCS.

    
	
  • RCS'ing Hardlinked Files
    
	Since editing any one of a number of hardlinked files 
	changes all of them, RCS is not a good option for hardlinked
	files.  RCS deletes and restores files.  This process 
	destroys the links, and editing one file no longer changes
	the others.  For example, it would be nice to have backup copies 
	of the files in /etc/rc0.d/, but they are hard 
	linked.

    
	
  • Breaking a Lock and Editing
    
	If someone has checked out and locked a file named FILE, and
	you have a very good reason to edit it, you can break the 
	lock, but be careful! Locks are broken like this:

    
	% rcs -u FILE

    
	You will be prompted for the reason why you broke the 
	lock.  Before editing the file, do this:

    
		
      
		
    1. See if the working file and the RCS file have
		any differences.

      
		% rcsdiff FILE

       
		
    2. If there are differences, make another copy
		of FILE, for instance FILE.bak.

      
		
    3. % co -l FILE

      
		
    4. If there were differences, the latest revision
		of FILE has just been nuked.  Copy FILE.bak to
		FILE.

      
		
    5. % ci -u FILE

      
		
    
	
  
  MENU



More Information About RCS

RCS man pages:
	
    
	
  • ci(1)
    
	check in a file
	

    
	
  • co(1)
    
	check out a file
	

    
	
  • ident(1)
    
	display all keywords
	

    
	
  • rcs(1)
    
	revision control system
	

    
	
  • rcsdiff(1)
    
	find differences between versions of a file
	

    
	
  • rcsintro(1)
    
	introduction to RCS, what it is, what it does
	

    
	
  • rcsmerge(1)
    
	merge two revisions of a file
	

    
	
  • rlog(1)
    
	display keyword with all log entries
	

    
	
  • rcsfile(5)
    
	contents of a RCS file
	

    
	


You might also want to look at CVS.

MENU




   Copyright (c)    HMC Computer Science Department.
      Permission is granted to copy, distribute and/or modify this document
      under the terms of the GNU Free Documentation License, Version 1.1
      or any later version published by the Free Software Foundation;
      with the no Invariant Sections, with no
      Front-Cover Texts, and with no Back-Cover Texts.
      A copy of the license is included in the section entitled ``GNU Free Documentation License.''




  

    HMC Computer Science Department

	Contact Information





Last Modified Monday, 27-Jan-2003 15:18:21 PST