Simple SVN: Just enough to get started.

Unless you have been living in an underground bunker, you have probably heard of Version Control, and possibly even Subversion (SVN). If you want to get the latest source code to compile it yourself, contribute to an open source project, keep track of files and documents, or work on the same document tree with a team of people, then you will need to use SVN. This article is not meant to be a substitute for the great documentation found at the Subversion website, but is instead meant to act as a quickstart guide to get regular folks over the hump of using SVN. SVN can seem very intimidating with its numerous command line switches and options, but it really isn’t all that complicated with a little practice.

Getting started

You will need to have subversion installed. As always, the rpm (Red Hat Package Management) system makes this easy. Let’s check to see if the package is installed.

rpm -q subversion

If the output is something like this:

subversion-1.4.3-0.1.el4.rf

Then you’re all set to start using subversion. If the package is not found, then simply type in:

yum install subversion

Creating a local subversion repository

The best way to understand how subversion works is to jump in with both feet. Let’s create a subversion repository on your machine that you will use to store your version control database. To create a subversion repository, just type in this command:

svnadmin create /usr/local/svn/squidrepo

Go ahead and see what that did. Change into that directory and do an ls:

cd /usr/local/svn/squidrepo
ls -l

You should see a bunch of directories:

conf/ dav/ db/ format hooks/ locks/ README.txt

If this looks scary, weird, and confusing, it should. You don’t want to touch this directory yourself! It is just a directory that SVN uses internally to keep track of changes. You won’t ever need to go in this directory unless you’re doing advanced systems administration on subversion.

Importing a directory into version control

Keeping track of changes to configuration files is a great use for a svn repository. If you have read my articles on squid, you might be thinking, let’s put the squid configuration files into svn. You’re correct; that is a perfect use of subversion. Let’s do an import to get started. In order to use svn, you must first import a working directory full of items you would like to keep track of changes on. To keep track of changes on the squid configuration directory, issue this (one line) command:

svn import -m "initial import of /etc/squid directory" /etc/squid file:///usr/local/svn/squidrepo/

What this does is import your squid configuration directory into the svn version control system. One very tricky detail is that a lot of people think you’re done and that you can now start using version control on the /etc/squid directory. This is wrong! You have only imported the directory. Only subsequent checkouts of the source code from subversion will allow you to maintain versioning.

Let me give you an example. Go ahead and check out the source code into a “sandbox” directory first. Let’s make that sandbox now:

mkdir /tmp/sandbox

Then change into the sandbox:

cd /tmp/sandbox

Then check out the source code we checked in:

svn co file:///usr/local/svn/squidrepo squid

If you notice, you checked out the subdirectory “squid”.

Now type in this command, and note that I am selecting etc/squid and NOT /etc/squid.  This is very important /etc/squid is your working configuration directory!:

svn co file:///usr/local/svn/squidrepo etc/squid

This time you checked out the whole directory tree you originally imported. Subversion will let you decide to if you want to check out a directory or a directory tree.

Implementing version control for Squid configuration files

So now that you know how to import and checkout code, the next step is to actually implement this with your /etc/squid directory. I want to put a word of caution out. If you are on a production server, do not do this step until you have practiced it in a sandbox and feel 100% comfortable. It is never a good idea to move, change, or delete configuration files without a backup, either.

First, stop squid if it is running:

service squid stop

Backup squid configuration directory:

mv /etc/squid /etc/backup_squid

Change into the /etc directory:

cd /etc

Now check the squid file out of version control:

svn co file:///usr/local/svn/squidrepo squid

Now start the squid service again:

service squid on

Using version control to keep track of Squid configuration files: A whirlwind tour

Now that we have a working copy out of svn, and it lives in the correct directory, we can start testing out some of the fun features of subversion. Let’s get some information. If you’re in the /etc/squid directory, issue this command:

svn info

You should see some type of output like this:

[root@cent squid]# svn infornPath: .

URL: file:///usr/local/svn/squidrepo
Repository UUID: cd285af0-e034-0410-ad4e-8dbcf155913f
Revision: 1
Node Kind: directory
Schedule: normal
Last Changed Author: root
Last Changed Rev: 1
Last Changed Date: 2007-07-10 04:19:25 +0000 (Tue, 10 Jul 2007)

This command tells you who checked in this copy, when, and where it is located in the repository, etc.

Next, let’s do something fun. Let’s change our configuration file and add some nonsense to it. Then make svn revert it back to the original condition. Open up /etc/squid/squid.conf and with your favorite text editor, add the following line to the top of the file. I like to use vim, so for me it is:

vim /etc/squid/squid.conf

"This is completely incorrect text. Subversion will help me get rid of it though!"

Now restart squid and see it complain:

service squid restart

You should see an error message like this:

Stopping squid: 2007/07/10 05:01:45| parseConfigFile: line 1 unrecognized: '"This is completely incorrect text. Subversion will help me get rid of it though!"'.
[ OK ]
Starting squid: . [ OK ]

That is annoying. Let’s get rid of the error by using svn to revert the file. Simply type in the following command:

svn revert /etc/squid/squid.conf

You should get back the following message:

Reverted '/etc/squid/squid.conf'

Now restart squid and you will see that the error message went away.

service squid restart
Stopping squid: .. [ OK ]
Starting squid: . [ OK ]

As you can see, this is incredibly powerful, as you can completely screw up your config file and then revert it back in a millisecond. (Of course this all depends on you remembering to commit changes to svn every time you make a modification to your files.) Let’s test this out by adding a simple comment to our squid config file and then committing the changes.

Open /etc/squid/squid.conf and add the following to the top of the squid file:

#First SVN Import

Now commit the changes; remember, you should to be inside /etc/squid:

svn commit -m "added a comment to my /etc/squid/squid.conf file"

You now should get the following feedback:

Sending squid.conf
Transmitting file data .
Committed revision 2.

That feedback tells you that you just committed a change revision number 2. If you ever want to see what is in your svn repository, just type in the command:

svn list

Summary

Our Whistle-stop tour went through creating a local subversion repository, importing a directory tree into version control, implementing version control on a config file directory tree and finally, using svn to revert and make changes to config files. This is probably enough svn to get you started for a while, but I would highly recommend reading the svn book, or at least keeping it around as a reference. Remember, version control can keep your important data and keep it safe. Everyone should be using some sort of version control!  If you use svn to keep track of your configuration files or important documents, I would love to hear how it has saved your day.  This will be great motivation for people who haven’t decided to use version control yet.

This entry was posted by Noah Gift on Tuesday, July 17th, 2007 at 3:38 pm and is filed under documentation, technical. You can follow any responses to this entry through the RSS 2.0 feed. Both comments and pings are currently closed.