Rate this page del.icio.us  Digg slashdot StumbleUpon

Simple SVN: Just enough to get started.

by

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.

Tip
When you do an import into subversion, you must “delete” your original import directory in order to make it under version control. The reason for this is that svn puts files inside of the checkout tree to keep track of changes. The only way to create these files is through a brand new checkout. The safest way to do this is to backup your original directory by moving it and renaming it, and then do a checkout in that directory.

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.

16 responses to “Simple SVN: Just enough to get started.”

  1. Michael J Gruber says:

    There is a much simpler approach to making an existing directory into a versioned working copy:

    create the repo as above (it will be empty)

    checkout (svn co) the empty repo over your directory (e.g. /etc/squid): This will do nothing but add “.svn” directories.

    add (svn add) any files you want to be version conrolled

    checkin (svn ci) the first revision

    This is documented at http://subversion.tigris.org/faq.html#in-place-import

    The advantage of this approach is that you do not have to stop any services because there is no need to move directories around.

  2. Noah Gift says:

    Michael,

    That is a great tip! I will start using it next time I add a new directory tree. Goes to show you I have not read the whole subversion manual, just use it as a reference. I treat svn a little like vim, when something seems inefficient I do some research to find out if there is an efficient way to do it.

    I think for newbies doing it for the first time, they might understand the concepts better doing my method described above. After they have the hang of it they should switch to the method you describe as it much more efficient.

    Again, great tip!

  3. michuk says:

    Another decent Subversion HOWTO: http://polishlinux.org/apps/subversion-howto/
    (basing on Apache2 and SSL)

  4. Ashish says:

    Would have been better had you left squid out of it.

    What was the need?

  5. Noah Gift says:

    Michuk,

    That is a good article on the server side. Good tip!

  6. Noah Gift says:

    Ashish,

    Since I happen to write code all day long these days, I figured an example using a typical code source tree wouldn’t be as fun. I do agree with you on the fact that there are many interesting ways to use svn, if that is what you meant.

    A creative examples, would be to manage an Music Collection. SVN does binary files as well.

  7. Everything is a Funky DNS Problem ! says:

    Red Hat Magazine | Simple SVN: Just enough to get started.

    Red Hat Magazine
    runs an article titled Simple SVN: Just enough to get started

    It’s about time system administrators also learn to use version control for their own configuration files and not just for the code their developers are usin…

  8. Noah Gift says:

    EIAFDP,

    I agree! Version Control for sysadmins is way over due! Thus the article :)

  9. Mike says:

    Please check above link, You can setup Subversion apache active directory within few clicks

  10. Mike says:

    http://opensourcedevelopment.net/text-tutorials/apache-subversion-active-directory.html

  11. Tom says:

    Is there a way you can ever remove very old revisions of your files from the repository?

  12. Noah Gift says:

    Tom,

    The nice thing about svn is that you can keep revisions forever. You don’t want to delete versions in the repository. If you type in:

    svn log

    It will show you your revision history and you can easily revert back to those changes. Deleting things permanently is not a good idea, unless you for some reason committed 200GB of data :) In that case, you can delete revisions, but you can refer to the manual for that.

  13. Thomas Vander Stichele says:

    SVN doesn’t deal with two important things you want it to deal with when you want to store your config in it.

    One is permissions/ownership. The other is SELinux context – I doubt the example given will actually work as listed on a machine with SELinux.

    I’ve started writing a project that deals with both these problems:
    https://thomas.apestaart.org/thomas/trac/wiki/projects/savon

  14. RajDeep says:

    Realy gr8 article to start with …. :)

  15. Mark says:

    Hi -

    Thanks for taking the time to put this page together. I was moving along fine through the test sandbox phase of the steps, however when it came time to actually check the file out into the real directory, I ran into this error:

    svn: Failed to add file ‘orderform/processorder.php’: object of the same name already exists

    It appears you need to delete the original files from the live directory after creating the repository and then check the files out to the directory? At least that is how I resolved the issue.

  16.   Weekly links roundup by Communications from DMN says:

    [...] Here’s the basics of Subversion. You never know when you’re going to need it [...]