An RCS Primer
RCS, which stands for revision control system, is designed to manage the editing of files in any sort of development project. When used properly, it prevents people from editing the same file at the same time, provides a history of changes, and simplifies administration of projects.
The first and most important thing to understand is the state of file. A file can be in one of three states:
1. Not under RCS.
2. Under RCS, unlocked.
3. Under RCS, locked.
Unlocked implies that nobody has locked the file in preparation for editing. Locked implies that somebody has checked out the file so that only they can edit it. When a file has been checked out and locked, anybody else he tries to edit will get a permission denied problem. When nobody has a file checked out, nobody will be able to edit. Note that it is possible to get around this if you try hard enough; so, the most important thing to remember is: if you cannot edit a file, it is probably not checked out properly for you. Go ahead and try to check it out, and see if that rectifies the problem.
Getting Started with RCS
In order to use the RCS system, there should be in RCS subdirectory in each directory of your website on the development server. You should create an RCS subdirectory in any directory where you would like to use RCS. If you don't, checking in files will create files ending in ,v in the same directory as the regular files. If this happens, don't panic; simply make the RCS directory at that time and move all of the files ending in ,v into that subdirectory.
These are the UNIX commands used to manage things under RCS. They are all run from the command line, and work on any file or files:
- ci - check in a file
- co - check out a file
- rlog - get the history of a file
- rcsinfo - show who's working on files in a directory
- rcs - run auxiliary commands to lock and unlock files
In its most simple form, RCS is very quick and convenient. To edit a file that has already been put under RCS, simply run the following commands:
co -l <file> [ check out a file
and LOCK it ]
[ perform your edit of the file now,
via FTP, whatever ]
ci -u <file> [ check the file in
and UNLOCK it ]
And that's it! Basically, whatever you want to edit a file, you simply have to bracket the edit with the co and ci commands.
Here's a sample:
corona /tmp 58# co -l foo.html foo.html,v --> foo.html revision 1.1 (locked) done [ FILE EDIT DONE HERE ] corona /tmp 57# ci -u foo.html foo.html,v <-- foo.html new revision: 1.2; previous revision: 1.1 enter log message, terminated with single '.' or end of file: >> Added new section. >> . done
As you can see, version 1.1 of the file was checked out, and when I checked it back in, I was given the opportunity to put in a comment and the version was incremented to 1.2.
Initial Check-In
The first time you want to edit a file that has not yet been put under RCS, you'll need to check it in. So, if the co command fails, because the file is not under RCS, simply perform the initial check and you'll be able to edit the file normally under RCS going forward:
ci -l <file>
This will give you a checked-out, locked version of version 1.1 to start editing.
Image Files
Images, and other binary files, can be used with RCS. However, it's only helpful to keep a history, since you can't easily view differences in binary files. I recommend against using RCS to manage these types of files.
More Gory Details
Naturally, there are other commands which you'll find useful, particularly if something goes wrong.
Viewing History
You can view the edit history of a file with the rlog command:
corona /tmp 59# rlog foo.html | more RCS file: foo.html,v Working file: foo.html head: 1.2 branch: locks: strict davidb: 1.2 access list: symbolic names: keyword substitution: kv total revisions: 2; selected revisions: 2 description: ---------------------------- revision 1.2 locked by: davidb; date: 2000/01/11 16:36:40; author: davidb; state: Exp; lines: +1 -0 Added new section. ---------------------------- revision 1.1 date: 2000/01/11 16:36:13; author: davidb; state: Exp; Initial revision
Whatever comments people put into the file are listed at the bottom, where it shows the revisions in order. Each revision indicates how many lines were added or deleted (+1 -0 in 1.2), and who was the author of that particular change. Near the top, where it says "locks", indicates if anyone has the file locked. In this case, I have locked version 1.2, so I could go ahead and edit it.
Seeing Who's At Work
The rcsinfo command will show you any files that are checked out in the current directory. If you add the -l option, it will show you who exactly is working on them:
corona /tmp 60# rcsinfo -l foo.html v1.2 locked by: davidb 01/11/100 11:36
Stealing Somebody Else's Lock
Sometimes, somebody else will leave a file locked and forget to check it back in. In this case, you have to use the rcs command to steal the lock. First, check to see who has the file checked out using the rcsinfo command and try to contact them to make sure they aren't actually using the file. If the file is a couple of days old at that point, you can steal the lock as follows:
rcs -l <file> #This steals the lock for you
ci -l <file> #This command check's THEIR
version in, and checks it
OUT again locked by you so
you can edit it.
If that other person had made changes to the file, you'll be prompted to enter a comment about the revisions. Otherwise, the file will be checked back out in your name:
corona /tmp 3$ rcs -l foo.html RCS file: RCS/foo.html,v Revision 1.2 is already locked by davidb. Do you want to break the lock? [ny](n): y State the reason for breaking the lock: (terminate with single '.' or end of file) >> I need to work on it. >> . 1.2 unlocked 1.2 locked done corona /tmp 4$ ci -l foo.html RCS/foo.html,v <-- foo.html file is unchanged; reverting to previous revision 1.2
Viewing Differences
Sometimes, you will want to see the differences in a file you are editing, or between previous revisions. There is a very nice command to do this called rcsdiff, which will show you these differences in "diff" format. It's not very friendly to read, but will give you an idea of what has changed. To see the difference between the current version and any edit to have made that are not checked in, simply run the command as follows:
rcsdiff <file>
You can look at the differences into revisions by specifying them on the command line:
rcsdiff -r1.1 -r1.2 <file>
For example:
corona /tmp/test 11$ rcsdiff -r1.1 foo.html ============================================= RCS file: RCS/foo.html,v retrieving revision 1.1 diff -r1.1 foo.html 0a1 > Made changes
Which shows that I added a line to the file.
Missing File
A somebody calls the ci command and forget to say -u or -l, the file will "disappear". Don't panic; the file is still there, is just stored under the RCS subdirectory in the current working directory. To get back, simply do a:
co -u <file>