Whether it’s source code or system configuration files, it’s nice to be able to keep track of changes made to files over time. The Revision Control System is a collection of programs that keep track of different versions (revisions) of text files. A special file is created by RCS that contains information about the changes in a file and allow the user to get back to any revision of the file.
RCS was designed primarily for programmers to keep track of what changes were made to various source files. It was derived from an earlier Source Code Control System (SCCS) and was first developed for the UNIX operating system.
Since RCS came from a UNIX background, it understands the concepts of different users accessing the same files and allows “checking out” files and locking them from being changed by other users. RCS can be used by a number of programmers all working on the same code. It keeps track of who has what file “checked out” and who makes what changes.
Although most QL programmers program by themselves, RCS can help the QL programmer bring a form of discipline to their programming. This is especially usefull for what can be called “full production” programs; commercial or freeware. Given the long life of QL programs (I’m still using programs written more than 10 years ago), RCS can keep track of what changes were made from revision to revision and why. A programmer can keep make a rule that each RCS revision be a bug fix and the reasons for the fix can be logged as part of the revision history.
Enough blathering on, now to jump right into what RCS is and how it works.
Original File – This is the text or source code file that you want to keep track of. It can be any text file.
Revision File – This is a single file that contains the original text/source file and all of the revision history. It has the same name as the original file except that a ‘,v’ is appended to the end. If the original file is ‘test_c’, then the revision file is called ‘test_c,v’. A revision file keeps track of only one original test/source file. If you have 3 source code files that make up a single executable, then RCS will have three revision fills.
Check-In – All revisions to a file are put into the revision file by checking them in. The program ‘ci’ is used to do this. ‘ci’ is used to either create a new revision file or to check-in a new revision into an existing revision file. Once a file has been checked into the revision file, it is deleted.
Check-Out – When you want to edit a text/source file that has been checked in to the revision file, you use ‘co’ (check-out) to extract the text/source file from the revision file.
The whole process of using RCS is basically checking-in and checking-out the same file. RCS is not aware of time, so there is no need to check-in a text file when you have finished a programming session. You really only need to check-in a file when you have made all of the edits you need. If you are fixing a bug in a program, you would only check-in the file when you have fixed it. No need to keep track of working copies of the files.
To show you how RCS is used, I’ve written a short Structured SuperBasic program:
OPEN #3,con_100x100a100x100
CLS #3
INPUT "Enter The Name of a File :";file$
OPEN_IN #4,file$
REPeat loop
INPUT #4,in$
IF EOF(#4) THEN EXIT loop
PRINT #3,in$
END REPeat loop
CLOSE #4
CLOSE #3
I stored this program in the file ‘readfile_ssb’. I then checked it in to RCS using the following command:
exec ci;"readfile_ssb"
‘ci’ then asks me for my initials. Since the QL does not have the concept of multiple users (and therefore user names), a persons initials are used to keep track of who has checked out a file and who has made what changes to that file. ‘ci’ then asks for a Description. The Description is where the “why” of the file change is kept track of. If you are using RCS to keep track of bug fixs for a program, the Description section would be used to mention the bug, what caused it, and how it was fixed. I do not believe there is a limit on how long the description can be. The Description is ended by a line with just a period on it.
‘readfile_ssb’ is now checked-in to the RCS revision file and is deleted.
Now to get the file back to edit it, I ran the following command:
exec co;"-l readfile_ssb"
I need to tell ‘co’ what file I want, but I also have to tell ‘co’ that I want to edit the file. If I ran ‘co’ without the “-l” option, ‘readfile_ssb’ would have been created, but it would not have been “checked-out” from the revision file, and when I went to check it in, RCS would not have allowed it. Under UNIX, ‘co’ would create a ‘read-only’ copy of the file.
‘co’ asked for my initials. Since the same person who checks out a file is the only person the can check in a file, be sure to remember what initials you used.
‘readfile_ssb’ is now extracted from the RCS file and the revision file is changed to show that the file is checked out.
Once I am done editing the file, I can then check in the file using ‘ci’. Again I am asked for my initials. The file is now checked back into the revision file and deleted. If you copied the file before checking it back in and you have edited this file, you can not incorporate those changes into the revsion file since the file is ‘officially’ checked in and can not be edited.
RCS uses revsion numbers to keep track of the different times a file is checked-in. The first revision is 1.1, then 1.2, then 1.3 and so on. Let’s say that I have edited my file 4 times, I’m now at revision 1.5 and want to recall revision 1.3. I would run the following command:
exec co;"-r 1.3 readfile_ssb"
‘co’ would then dig though the revision history and generate version 1.3 of ‘readfile_ssb’.
RCS comes with more than just the ‘ci’ and ‘co’ programs. ‘rcsdiff’ is used to compare a working “checked-out” file with the version still in the revision file. ‘rlog’ is used to view the revision file.
Below is the output of ‘rlog’ from my example session:
RCS file: readfile_ssb,v
Working file: readfile_ssb
head: 1.2
branch:
locks: strict
access list:
symbolic names:
comment leader: "# "
keyword substitution: kv
total revisions: 2;selected revisions: 2
description:
Creation of RCS Archive
----------------------------
revision 1.2
date: 1998/06/11 20:41:01; author: tcs; state: Exp; lines: +2
-2
This is a second version of this program.
----------------------------
revision 1.1
date: 1998/06/11 20:19:34; author: tcs; state: Exp;
Initial revision
============================================================
RCS is a lot more complicated that I’ve mentioned here. It, and SCCS, is fully documented in the book “Applying RCS and SCCS” by Bolinger & Bronson, published by O’Reilly & Associates. RCS for the QL is available from most freeware sources. The QL RCS distribution does not come with the ‘diff’ program which it requires. ‘diff’ is available as part of the C68 distribution.
RCS can not be used with regular SuperBasic programming, as RCS would see any new line numbers as a change in the file. If you loaded a file into SuperBasic, did only a line renumber, saved it, and then check it back into RCS, RCS would any line with new line number as having changed. RCS works well with Structured SuperBasic as it has no line numbers. It also works well with C, Forth, Pascal, etc.