Keeping Track of Change

For years, software developers have been keeping track of all their changes to programs they are developing with what they call “version control” software. However, even competent developers have sometimes found it too troublesome to use these tools except where they find it absolutely necessary, and so it is not surprising that very few non-developers have used these tools at all.

The reason that they find these tools so difficult to use is that the rules for how to use them are written with the most complicated situations in mind. For most personal use of these tools, that is like learning to fly a jet aircraft in order to drive a car. There is an easier way.

The assumption that makes everyone do so much extra work is that more than one person will be trying to modify the file at the same time. For your own personal files, or for keeping track of changes to system files when you are the only system administrator, that is not an issue.

The standard program for doing version control under Linux (and most other versions of Unix) is GNU's RCS, which stands for Revision Control System. It has many options, but you hardly need to know about any of them to make good use of it. You can treat RCS as one of the simplest tools on your system.

In fact, you can keep track of all the changes that you ever make to a file with one command. Run the command ci -l filename each time you make a change to the file (“ci” stands for “check in”; you are “checking in your changes”). The first time you do this, you will be given the option to describe the file:

$ ci -l foo
foo,v  <--  foo
enter description, terminated with single '.'
  or end of file:
NOTE: This is NOT the log message!
>

You are not required to describe the file, but you can if you like. Then type a . character on its own line, or press ^D on an empty line.

When you have made a change to the file, you need type only one command to tell RCS to keep track of that change for you:

$ ci -l foo
foo,v  <--  foo
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single '.'
  or end of file:
>

Here, you may wish to describe the change you have just made, especially if you think you will want to examine the change at some future time, but it is not required.

Remembering that single command is enough to prepare you for disaster. The rest of this short article will show you a few easy tricks that make RCS a little more comfortable to use, and help you learn how to recover from disaster.

If you think running one command each time you finish editing a file is still too much work, we can make it even easier for you! (Laziness is a virtue if it causes you to work smarter instead of harder.)

We'll use a shell script. You can create a file in your own “bin” directory (if your account is on a computer shared with other people) or in /usr/local/bin (if you are using your own computer). Whichever directory you choose must be listed in your PATH. To make it easy to type, we'll call it et, short for edit text.

#!/bin/bash
# et - Edit Text file, while keeping
#      track of changes with RCS
[ -z "$1" ] && {
  # No file specified on the command line
  echo "Edit what file?"
  exit 1
}
${EDITOR-vi} $1
# Only check in the file if it exists.
[ -f $1 ] && ci -l $1

Type that into a file named et, without making any typos. Then run the command chmod +x et to make the file executable. Now, you will be able to run et filename to edit and then automatically check in your changes.

The #!/bin/bash line tells Linux this script is a shell script that is interpreted by the bash shell, which comes as a standard part of every Linux distribution. All the other lines starting with a # character are comments, and are ignored by bash.

If you decide that you will never want to include a description of the changes you have made, you can change the last line of the script to

[ -f $1 ] && echo "." | ci -l $1

The reason for the [ -f $1 ] part is so that if you type et mistake, and then quit the editor without saving the file, you won't get error messages when ci finds that there is no file for it to check in.

The ${EDITOR-vi} part runs your favorite editor, or if you have not chosen a favorite editor, it defaults to the old standard vi editor. You can choose a default other than vi; pico, jed, joe, Emacs, and other editors are all possibilities. For example:

${EDITOR-jed} $1

will run jed, unless you have chosen some other favorite editor.

To choose your favorite editor, which will apply to all programs that want you to choose an editor, not just et, you will need to set the EDITOR environment variable to the name of the editor you want to use. If you are using a bourne shell, such as bash, zsh, pdksh, ksh, or sh, you will want to add a line like the following to the file .profile in your home directory:

EDITOR=jed ; export EDITOR

If you use the C shell (csh or tcsh), you will want to add a line like the following to the file .login in your home directory:

setenv EDITOR jed

RCS doesn't keep a whole new copy of the file each time you check in changes. Instead, it records only the lines with changes in them, along with the descriptions of the changes (if you choose to provide them). It does this in a separate file. Changes to the file filename are kept in the file filename,v. If you find this to be too much clutter, you can tell RCS to stash the filename,v file out of the way, in a subdirectory called RCS. Simply create the subdirectory, and RCS will automatically use it.

Remember what it looked like when the foo file was checked in, above? Let's create a bar file whose corresponding bar,v file is kept out of sight in an RCS directory:

$ mkdir RCS
$ vi bar
$ ci -l bar
RCS/bar,v  <--bar
enter description, terminated with single '.'
  or end of file:
NOTE: This is NOT the log message!
>
$ vi bar
$ ci -l bar
RCS/bar,v  <--  bar
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single '.'
  or end of file:
>

If you did not originally create an RCS directory, and you get tired of seeing the ,v files, you can use these commands to get them out of the way safely:

$ mkdir RCS
$ mv *,v RCS

RCS will know where to search for them.

So what do you do when you screw up? You have carefully kept copies of your changes, but how do you retrieve yesterday's version, or last year's version, or the second most recent version?

RCS keeps track of versions by version numbers. The first version you check in is assigned the number 1.1, the second is assigned the number 1.2, the third 1.3, and so on.

When you find that you have made a mistake, you can compare what you currently have with previous revisions. To compare against the previous revision, use this command:

$ rcsdiff -u filename

The -u tells rcsdiff to use the “unified diff” format to show you the changes, and it compares the current version of the file filename with the most recent version that was checked in. Here's an example. The previously checked in version of the file foo, version 1.3, consisted of:

This is a test of the emergency
RCS system.  This is only a test.

I have since edited the current version to read:

This is a test of the emergency
RCS version control system.
This is only a test.

Before checking this new version in, I can check the differences between the current contents of the file and the previous version that was checked in, giving me this:

$ rcsdiff -u foo
==============================================
RCS file: foo,v
retrieving revision 1.3
diff -u -r1.3 foo
--- foo 1996/02/01 00:34:15     1.3
+++ foo 1996/02/01 00:34:31
@@ -1,2 +1,3 @@
 This is a test of the emergency
-RCS system.  This is only a test.
+RCS version control system.
+This is only a test.

After showing what versions are being compared, the differences are shown. Lines that have not been changed are printed with a single space in front of them. Lines that have been removed in the newer version have a - in front of them, and lines that have been added have a + in front of them. As you can see, lines that are changed are considered to be deleted from the older version, and changed replacements added to the new version. Around any section with changed line, up to 3 lines of unchanged “context” will be shown to help you understand where in the file the change has been made.

This mechanism can be used to compare any two versions. After making a few more changes to the file, I can compare revision 1.6 to revision 1.3:

$ rcsdiff -u -r1.3 -r1.6 foo
==============================================
RCS file: foo,v
retrieving revision 1.3
retrieving revision 1.6
diff -u -r1.3 -r1.6
-- foo 1996/02/01 00:34:15     1.3
+++ foo 1996/02/01 01:05:28     1.6
@@ -1,2 +1,6 @@
 This is a test of the emergency
-RCS system.  This is only a test.
+RCS version control system.
+This is only a test.
+
+I'm now adding a few lines for
+the next version.

Note that it is good to list the earlier revision first. Otherwise, the sense of + and - are reversed.

Your changes are likely to be much more significant than these examples, and may take up more than a screen listing. This is not a problem; use a pager to view your output one screenful at a time:

$ rcsdiff -u -r1.3 -r1.6 foo | less

Once you see the changes you have made, you can usually figure out where you made your mistake and fix it by hand. Sometimes you might have accidentally done damage that is large and confusing, but more often you have changed a phrase or a paragraph, are dissatisfied with your change, and simply can't remember exactly what it used to look like.

If you want to, you can store a copy of the changes in a file with a command like:

$ rcsdiff -u -r1.3 -r1.6 foo > filename

or print the changes like:

$ rcsdiff -u -r1.3 -r1.6 foo | lpr

If the time comes when you would rather simply revert to an older version, choose the version to which you wish to revert (call it 1.x) and run these commands:

$ ci -l foo
$ co -r1.x foo
RCS/foo,v  -->  foo
revision 1.x
writable foo exists; remove it? [ny](n): y
$ chmod +w foo

At this point, you have reverted to version 1.x of your file. From this point, you can continue making changes as if you had simply edited the latest version until it was identical to version 1.x.

Note that you should almost never have to do this; many people never have.

How do you figure out which versions to look at, when you are looking for one particular change? One command provides an instant summary of the changes that have been made since revision 1.1. This is where providing descriptions for important changes comes in handy. To see the log of all the changes, use the rlog command:

$ rlog bar
RCS file: RCS/bar,v
Working file: bar
head: 1.3
branch:
locks: strict
        johnsonm: 1.3
access list:
symbolic names:
keyword substitution: kv
total revisions: 3;     selected revisions: 3
description:
----------------------------
revision 1.3    locked by: johnsonm;
date: 1996/02/01 02:40:16;  author: johnsonm;
    state: Exp;  lines: +1 -0
Added different text.
----------------------------
revision 1.2
date: 1996/02/01 02:39:59;  author: johnsonm;
    state: Exp;  lines: +1 -0
Added some text.
----------------------------
revision 1.1
date: 1996/01/31 21:22:36;  author: johnsonm;
    state: Exp;
Initial revision
==============================================

The most important parts for you to understand are the revision descriptions at the end. For example, under the revision 1.2 section, there is a comment Added some text. This is the comment that you are allowed to type in after every revision. If you choose not to enter a comment, it says instead:

*** empty log message ***

which isn't particularly helpful when you are looking for a change you made.

On the other hand, if you find entering a comment to be so much work that you are tempted not to use RCS, you are better off when things go wrong to be able to go looking for the version you want than to have no information whatever. Don't avoid using RCS because you feel you ought to describe every revision...

These logs become very long, very quickly. In order to look at the log one screen at a time, use a pager program:

$ rlog bar | less

Again, you can send the log to a file or print it, if you prefer.

There is a lot more to RCS than can be found in this article, since this is a tutorial intended to make it easy for you to use RCS. If you are interested, RCS comes with a full complement of manual pages, as well as papers about how to use RCS in a development environment. In addition, Linux Journal had an earlier article on RCS, aimed more at developers, in the February 1995 issue. But don't think that you have to know everything about RCS in order to use it effectively.