Ask SIPB - November 13, 2007

Ever wanted to go back to yesterday's version of a file? Or figure out what you changed since last week? Maybe you want to let someone else make some edits to a document, but be able to see what they changed. This week we'll look at one solution for these questions: RCS, a common, lightweight version control system (VCS).

What is version control and why is it useful?

A version control system, or VCS, is a way to keep track of what changes have been made to a set of files, in what order, and by whom. Many VCSs also provide the ability to "lock" a file so that group members do not overwrite revisions made by others. At the heart of a VCS is a log of what each file looked like at various points in time, with some extra information about who made changes, and some comments about why the changes were made or what they do.

The fact that there is a log of changes made allows for changes to be "rolled back" if they are no longer desired. This ability eliminates a lot of the need for manual backups (though if your work is very important, you may want to back up your entire repository). This makes using a VCS a reasonable idea even for a one-person project, in that deleting a paragraph need not be permanent. Using a VCS is invaluable for collaborative projects -- keeping track of different people's changes is almost impossible otherwise. A VCS is a general tool, and can be applied to any group project, such as software development, web design, and column writing.

What version control systems are there, and which one should I use?

The most common version control systems for small-scale use are RCS (Revision Control System), CVS (Concurrent Versions System), and Subversion. All three of these are open-source; very large (usually software) projects sometimes use proprietary VCS software that has more advanced features. RCS is very simple (and one of the oldest VCSs), but is still a useful choice for simple projects such as the Ask SIPB column. CVS and Subversion are usually used for larger projects with complex structure, such as software development.

The VCS model has a central repository which houses the current state and history of the files under its control. To edit a file, then, a local copy must first be "checked out", and changes are made to this copy. Different systems approach check-outs differently: RCS creates a lock file so that only one person can be editing a file at oncce; CVS and Subversion allow multiple people to edit at once, and when their changes are checked in, the VCS merges them together. If conflicting edits are made, the last user to check-in must decide which to keep and which to discard.

How can I start using RCS?

RCS expects there to be a directory named RCS in each directory that has files under its control -- the revision history is stored in the file RCS/filename,v. Once you create such a directory (mkdir RCS), you can start using RCS.

When you first create a file, you must check it in to RCS to place it under version control. When you want to make changes, you can check it out and lock it. After you're done editing, you can check it back in and unlock it, so that other people can make their changes as well. Many people like to use separate check-out/check-in cycles to group related changes together.

The commands to check files in and out are ci (check-in) and co (check-out):

athena% co -l filename
athena% ci -u filename
The -l and -u arguments tell RCS to lock and unlock the file, respectively.

Note that if you check in a file after making changes to it, you will be prompted to type a log message describing the changes you made.

What other useful commands does RCS offer?

The rlog command allows you to view the history of changes made in RCS. For example:
athena% rlog rcsbasic.html
RCS file: RCS/rcsbasic.html,v
Working file: rcsbasic.html
[...]
total revisions: 3;	selected revisions: 3
description:
Basic check-in and check-out commands
----------------------------
revision 1.3
date: 2007/11/11 17:27:07;  author: kaduk;  state: Exp;  lines: +3 -3
Spelling, grammar, and markup (one each)
----------------------------
revision 1.2
date: 2007/11/11 16:32:12;  author: kaduk;  state: Exp;  lines: +1 -1
Properly terminate <h4> region
----------------------------
revision 1.1
date: 2007/11/11 16:30:51;  author: kaduk;  state: Exp;
Initial revision
=============================================================================
Here, the file rcsbasic.html has been checked in three times, all by user kaduk. He has left some (sparse) comments about what changes he made in the "commit log".

If you want to see the actual changes between two versions of a file, and not just a commit message, you can use the rcsdiff command:

athena% rcsdiff -r1.1 -r1.2 -u rcsbasic.html
RCS file: RCS/rcsbasic.html,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- rcsbasic.html       2007/11/11 16:30:51     1.1
+++ rcsbasic.html       2007/11/11 16:32:12     1.2
@@ -1,4 +1,4 @@
-<h4>How can I start using RCS?<h4>
+<h4>How can I start using RCS?</h4>
 
  RCS expects there to be a directory named RCS in each
   directory that has files under its control -- the revision histroy
Adding the -u flag to the rcsdiff provides context for the diff.

How do I revert to an older version?

Suppose that kaduk's changes at revision 1.3 were mistaken, and 1.2 was more accurate. You can check out the old version by adding the -r flag, similar to how you use it in rcsdiff:
athena% co -r1.2 rcsbasic.html
RCS/rcsbasic.html,v --> rcsbasic.html
revision 1.2
done
If you had wanted to redo the edit, you could add the -l flag too, to check out the old revision.

How can I use RCS with Emacs?

After creating the RCS directory as described above, you can check in and check out files in Emacs with the keystrokes C-x v v. When checking in a file after the first time, Emacs will open a buffer prompting you to enter a change comment. After entering your comment, C-c C-c will end your comment and check the file back into RCS.


To ask us a question, send email to sipb@mit.edu. We'll try to answer you quickly, and we can address your question in our next column. You can also stop by our office in W20-557 or call us at x3-7788 if you need help. Copies of each column and pointers to additional information are posted on our website: http://www.mit.edu/~asksipb/