Archive for 7th August 2009

RCS – The GNU Revision Control System.

Here is a copy of the original article I submitted to for publication in the magazine.

         RCS, or the GNU Revision Control System, is a system used to keep track of files that can be edited by many people, or for files that may need to be reverted back at some point in time. I’d like to concentrate on the latter, simply because I think it will actually pertain to more readers than the first reason might. If you have multiple people coding on a project, then you probably already know what a revision control system is, but if you don’t, read on, it’s much easier than it sounds I promise. I really love using Arch as a server distro. While many think it’s not up to the task, I think they are sadly mistaken, I think it’s a great server distro that is extremely flexible and easy to maintain. But I digress, that’s not what I wanted to talk about today. My point was that if you run a server, you make changes to configuration files quite often, and having a revision control system can come in quite handy. The reasons for using RCS are many, from keeping track of coding changes you make to your scripts and programs, to keeping track of changes to apache configuration files, to recipes for a dish that your trying to perfect. Regardless of the reason you may have for needing a revision control system, RCS should prove to be something worth your time to look into. It’s short learning curve and usefullness should be enough to tweak the interest of even the most reluctant users. I know it’s not always fun, but the old adage “Backup, backup, backup, backup.” has been ringing in my ears, and RCS proves to be just the tool for many of those backup jobs that sometimes might otherwise not get done. Using a revision control system does NOT have to be hard to do. It should be easy enough to become second nature and just natural to do in your day to day work. So, lets get started with this shall we ? First and formost, and perhaps the most complicated part j/k pacman -S rcs and the system installs RCS, so cool, so easy.

If we use the revision control system correctly, we should ensure two things.

1. We have a log of all change we have made to the file.

2. We can revert back to previous versions of the file with ease.

There are two main ways to use RCS.

1. Just use “co” and “ci” on files in any directory, there will be files created that match “file” but have a “,v” at the end of them. So you would have “file” and “file,v” in your directory.

2. Create a subdirectory named RCS in every directory you want to work in, and RCS will automatically store files there, and keep your work area clean. I prefer this method myself.

        You could get creative and create simlinks to ONE directory, but that’s outside the scope of this document, besides, having a RCS subdirectory in the directory your working in quickly lets you know that you should use RCS to edit these files. Create the RCS subdirectory with the command “mkdir RCS” anywhere you want to use RCS, see, I told you it’s not hard. Moving on…

       There are two commands that you will use the most. They aren’t hard to master at all. “ci” = check in, and “co” = check out. Pretty darn complicated so far isn’t it lol. Ok, lets see how we first start using RCS with a new file. Lets say we have a file we want revision control on. Lets call it “”. The very first thing we need to do is checking the file to RCS. Issue the command:

ci -u

       This will initialize the RCS version of the file. It will also ask you for a DESCRIPTION of the file. This is NOT a change log entry, it is for entering a description of the file. This can be a multiline description, when your done with that, put a single “.” (period) on one line and that finished the entry of the description. Woot!, you have now checked in your first file to RCS :) “Ok, now how do i check this bad boy out and make changes”, you ask. Glad you did, it’s just as easy. Now we want to check out and make some minor changes to it. So we need to issue the command:

co -l

       So, we now have checked out, so we can open it with our favorite text editor, and make any changes we want to. Then we save the file. This is the tricky part, the part AFTER you have saved the file, you must check the file back into RCS. This is where people drop the ball and forget to do the check in of the file. It’s really simple as well, in fact, we’ve already used the same command once before ! Now type in:

ci -u

       This immediately PROMPTS you for a change log entry. Again, this can span multiple lines if you need it to, just end the log entry with a . “period only” on a single line. For those of you that are like me, and will probably forget to check things back in, I wrote a quick script, called amazingly enough “RCSedit”. Okay, I actually hacked the thing from other examples I’ve seen, but I did cut it down quite a bit in the spirit of KISS. It’s very basic, but does the job very nicely. It will use whatever editor you tell it to, and it checks out the file using your editor, then once your done, it starts the check in procedure, so you never forget ! Nice eh, plus, you don’t even have to remember those command above, even though they were extremely simple.

——————— RCSedit Script ———————-

       This small script is used to open your default text editor, or nano if you don’t have a default editor set. Create an alias to it in your .bashrc, or put it in your PATH somewhere, and name it RCSedit. It then checks out the file, and when your done editing, it checks it back in for you, so you don’t accidentally forget that. (Trust me, it’s EASY to forget to check the files back in ! )

if [ ! "${EDITOR}" ]
/usr/bin/co -l $1
${EDITOR} $1
/usr/bin/ci -u $1


       Ok, so now we can initialize RCS by creating an RCS directory, we can initialize the file by running the check in command, we can check out the file and edit it, and finally check it back in. I sort of feel like hitting my red Staples button that says “That was easy”. :) So, what else do we need to do ? Here is a run down of commands that you might find useful. I highly suggest reading man pages for them to become familiar with all the options they have available. Below is a very basic set of commands that would probably do about 99% of what you might need to accomplish though.

mkdir RCS Create an RCS subdirectory for storing rcs initialized files.

ci -u filename Initialize the file

co -l filename Check out the file and lock it.

ci -u filename Check the file back in.

rlog filename Shows the long log of changes made to filename.

rcdiff filename Compares RCS revisions

rcs -u filename Overide a locked unchanged working file. In short, it “unlocks” the file. Use with care.

       Ok, so now we can do all sorts of stuff with RCS, but wait you say…. “How to I revert a file back to a previous version ?” GREAT QUESTION !!! It’s very easy as well. We don’t even need a new command we use some of the ones above, cool eh ? Lets say we have made several revisions to our script, but we decided the last changes just sucked bad, and we really just want to go back one revison to what was working before we fubared it. Not a problem. RCS to the rescue ! First, i’d use the rlog filename command to list all of my revisions, and revision numbers . Let us say my last revision was 1.2 and I want to go back to 1.1. it’s pretty easy really. Issue the commands:

rcs -u This unlocks our file.

co -l -r1.1 This checks out the revision number we want to use.

ci -u This checks in the current working version, which is 1.1.

       TaDa ! Version 1.1 is back in business !!! Play with this on some non-critical files, so you can see how this works. You can edit version 1.1, and it becomes 1.1.1, and you can also still edit version 1.2 and it becomes 1.2.1. Takes some getting used to, but you’ll soon get the hang of it, and be using revsion control, and wonder why you didn’t start doing this sooner. There you have it, the basics of RCS, see, it really was simple, and I hope it proves to be a useful tool for you, it has for me.

One final note, if you like use emacs, your in luck, emacs has built in support for RCS and other version control systems. ! :)