Unix/Linux – Using Revision Control System
Tracking Revisions to a File (Revision Control System)
The Revision Control System (RCS) is a set of tools for managing multiple revisions of a single file. To store a revision of a file so that RCS can keep track of it, you check in the file with RCS. This deposits the revision of the file in an RCS repository−−−a file that RCS uses to store all changes to that file. RCS makes a repository file with the same file name as the file you are checking in, but with a `,v’ extension appended to the name. For example, checking in the file `foo.text’ with RCS creates a repository file called `foo.text,v’.
Each time you want RCS to remember a revision of a file, you check in the file, and RCS writes to that file’s RCS repository the differences between the file and the last revision on record in the repository.
To access a revision of a file, you check out the revision from RCS. The revision is obtained from the file’s repository and is written to the current directory.
Although RCS is most often used with text files, you can also use it to keep track of revisions made to other kinds of files, such as image files and sound files.
Another revision control system, Concurrent Versions System (CVS), is used for tracking collections of multiple files whose revisions are made concurrently by multiple authors. While much less simple than RCS, it is very popular for managing free software projects on the Internet. See Info file `cvs.info’, node `Top’, for information on using CVS.
Checking In a File Revision
When you have a version of a file that you want to keep track of, use ci to check in that file with RCS. Type ci followed by the name of a file to deposit that file into the RCS repository. If the file has never before been checked in, ci prompts for a description to use for that file; each subsequent time the file is checked in, ci prompts for text to include in the file’s revision log. Log messages may contain more than one line of text; type a period (`.’) on a line by itself to end the entry. For example, suppose the file `novel’ contains this text:
This is a tale about many things, including a long voyage across America.
To check in the file `novel’ with RCS, type:
$ ci novel
novel,v 60;−− novel
enter description, terminated with single ‘.’ or end of file:
NOTE: This is NOT the log message!
62;62; The Great American Novel.
This command deposits the file in an RCS repository file called `novel,v’, and the original file, `novel’, is removed. To edit or access the file again, you must check out a revision of the file from RCS with which to work. Whenever you have a new revision that you want to save, use ci as before to check in the file.
This begins the process all over again.
For example, suppose you have checked out the first revision of `novel’ and changed the file so that it now looks like this:
This is a very long tale about a great many things, including my long voyage across America, and back home again.
To deposit this revision in RCS, type:
$ ci novel
novel,v 60;−− novel
new revision: 1.2; previous revision: 1.1
enter log message, terminated with single ‘.’ or end of file:
62;62; Second draft.
If you create a subdirectory called `RCS’ (in all uppercase letters) in the current directory, RCS recognizes this specially named directory instead of the current directory as the place to store the `,v’ revision files.
This helps reduce clutter in the directory you are working in. If the file you are depositing is a text file, you can have RCS insert a line of text, every time the file is checked out, containing the name of the file, the revision number, the date and time in the UTC (Coordinated Universal Time) time zone, and the user ID of the author. To do this, put the text `$’Id$ at a place in the file where you want this text to be written. You only need to do this once; each time you check the file out, RCS replaces this string in the file with the header text.
For example, this chapter was written to a file, `managing−files.texinfo’, whose revisions were tracked with RCS; the `$’Id$ string in this file currently reads:
$Id: managing−files.texinfo,v 1.32 2001/05/16 16:57:58 m Exp m $
Checking Out a File Revision
Use co to check out a revision of a file from an RCS repository. To check out the latest revision of a file that you intend to edit (and to check in later as a new revision), use the −l (for “lock”) option. Locking a revision in this fashion prevents overlapping changes being made to the file should another revision be accidentally checked out before this revision is checked in.
To check out the latest revision of the file `novel’ for editing, type:
$ co −l novel
This command checks out the latest revision of file `novel’ from the `novel,v’ repository, writing it to a file called `novel’ in the current directory. (If a file with that name already exists in the current directory, co asks whether or not to overwrite the file.) You can make changes to this file and then check it in as a new revision.
You can also check out a version of a file as read only, where changes cannot be written to it. Do this to check out a version to view only and not to edit. To check out the current version of a file for examination, type co followed by the name of the file.
To check out the current revision of file `novel’, but not permit changes to it, type:
$ co novel
This command checks out the latest revision of the file `novel’ from the RCS repository `novel,v’ (either from the current directory or in a subdirectory named `RCS’). To check out a version other than the most recent version, specify the version number to check out with the `−r’ option. Again, use the `−l’ option to allow the revision to be edited.
To check out revision 1.14 of file `novel’, type:
$ co −l −r1.14 novel
NOTE: Before checking out an old revision of a file, remember to check in the latest changes first, or they may be lost.
Viewing a File’s Revision Log
Use rlog to view the RCS revision log for a file−−type rlog followed by the name of a file to list all of the revisions of that file.
To view the revision log for file `novel’, type:
$ rlog novel
RCS file: novel,v
Working file: novel
keyword substitution: kv
total revisions: 2; selected revisions: 2
The Great American Novel.
date: 1991/06/20 15:31:44; author: leo; state: Exp; lines: +2 −2
date: 1991/06/21 19:03:58; author: leo; state: Exp;
This command outputs the revision log for the file `novel’; it lists information about the RCS repository, including its name (`novel,v’) and the name of the actual file (`novel’). It also shows that there are two revisions−−the first, which was checked in to RCS on 20 June 1991, and the second, which was checked in to RCS the next day, on 21 June 1991.