Source Code Management with Subversion

One of the most useful tools in a productive programmer's toolkit is the source code management software. Even if you are maintaining only one project at a time, you will probably find yourself needing to manage slightly different versions of the same code. And for projects having hundreds of files, remebering changes over time is humanly impossible. The solution is to use a source code management system like Subversion.
Even though Subversion is built to be used by multiple users from multiple locations, we will look at how to use Subversion as a single user. Even for a single user, Subversion has huge pay-offs. As a programmer, you should be concentrating on solving problems instead of cluttering your memory with changes made to your code 3 months back. Lets look at what Subversion brings to the table:

Subversion: Intro

Subversion is a Open Source Project with Apache/BSD style Licence. You can download the Linux/Windows binaries and source code from http://subversion.tigris.org. Subversion was built with the intention of being a compelling replacement for CVS(www.cvshome.org). CVS is one of the oldest and widely used version control system out there and the age is showing. Subversion tries to be a better CVS, so it has most of CVS's feaures, as well having some of the features that are either missing or hacked together in CVS.
Subversion is usually referred to as SVN, which is also the name of its command line client.

Architecture of Subversion


The image above gives you bird's eye view of SVN's architecture. At one end you have the Subversion's repository that holds the versioned data. By default, the versioned data is stored in a Berkeley DB database, but in the later versions the OS's underlying FileSystem can be used to store data. This implementation is called FSFS. Both are equally good for a single users with differences becoming evident in larger projects. You can stick with the default option for the time being.
On the other end is the SVN's client program, which manages local reflections of portions of that versioned data ("working copy"). Between these two extremes, there are many Repository Access ("RA") layers which transport data back and forth. As you can see, the repository can be in a geographically different location and still be accessed over a web server (Apache) or Suversion's stand alone server, SVNServe. Secure transfer of files over the network can be achieving with SSH tunneling.

Installing Subversion

Subversion runs on most well known operating systems including GNU/Linux,Windows, BSD and Mac OSX. As the saying goes,The proof of the pudding is in the eating, we will learn about Subversion by working on it.
Assuming that you have Subversion on your system, lets proceed further. Subversion has several pieces of software, we will be using only two of these:

svn
the command-line client program
svnadmin
A tool for creating, tweaking or repairing a Subversion repository.

Setting up the Repository

Subversion stores all versioned data in a central repository. As a good practice, do not put the repository on your OS's root partition; ie., / on UNIX and c:\ on Windows, but rather in /home/ or d:\. This eases your backup chores and avoids data loss in case of an OS corruption.
Note: The examples shown here are from a GNU/Linux System running Subversion. But the commands remain the same even on Windows.
Create a new repository:

pgowda@3[~]$ svnadmin create repos /home/pgowda/repos
pgowda@3[~]$ cd repos
pgowda@3[repos]$ ls
conf  dav  db  format  hooks  locks  README.txt
Thats it! Your source code management system is up and running. Lets see how to put your existing projects into the repository.

Importing data into the repository

Lets say you have a project with 3 files in it under source directory (user.php, test.php, global.php). Create 3 sub directories under source and move all the files to trunk. We will look at the reasons later.

/home/pgowda/source/
		/branches/
		/tags/
		/trunk/
			global.php
			test.php
			user.php
Import the source tree to Subversion repository:
pgowda@3[~]$ svn import source/ file:///home/pgowda/repos/project1 -m 'Initial Import'
Adding         source/user.php
Adding         source/test.php
Adding         source/global.php

Committed revision 1.
The -m option specfies the comments for this transaction.
The tree structure is replicated inside the repository. You can see the contents of project1 with the svn ls command.
pgowda@3[~]$ svn ls file:///home/pgowda/repos/project1
global.php
test.php
user.php
Your code is now in the repository. You can delete your 'source' directory now. Go ahead! do it.
On a day-to-day basis, your interaction with subversion can be reduced to a 'work cycle'.

Work Cycle

Code Check out

When you start working on an existing project, you start with checking out the existing code on to your local directory. Check out creates a 'working copy' or 'sand box' of the project.
pgowda@3[~]$ svn co file:///home/pgowda/repos/project1 ./sandbox
A  sandbox/user.php
A  sandbox/test.php
A  sandbox/global.php
Checked out revision 1.
You can do whatever you want with this code without worrying about making mistakes. If you end up borking the code, dont panic! do an svn revert.
pgowda@3[sandbox]$ svn revert user.php
Lets go ahead and make some changes to the source files. So, if you want to know what files you have modified since checkout, do an svn status .
pgowda@3[sandbox]$ svn status
M      user.php
What if you want to know which lines have changed?
pgowda@3[sandbox]$ svn diff
Index: user.php
===================================================================
--- user.php    (revision 1)
+++ user.php    (working copy)
@@ -0,0 +1,4 @@
+/**
+user.php - handles user authentication
+
+*/
diff is one of most useful tools in a version control toolkit. In the lines above, new lines are prefixed with a + and removed lines with a -. Lets say we want to add a new file to our project (funcs.php). Go ahead and create a new file under 'sandbox' and save the code. But when you do svn status:
pgowda@3[sandbox]$ svn status
?      funcs.php
M      user.php
Thats because svn does not recognise funcs.php, yet. To add this file to the repository:
pgowda@3[sandbox]$ svn add funcs.php
A         funcs.php
Other file operations like move, copy and delete work similarly.
After hours of coding you want to skip over to lunch. But wait! check in your code first, lest a virus (or a martian-passing-by) gobble up your precious files for lunch.
pgowda@3[sandbox]$ svn commit -m 'added header info and new library file'
Adding         funcs.php
Sending        user.php
Transmitting file data ..
Committed revision 2.
Give comments which are concise and useful, because they are going to be helpful to you in the long run.
You must do an svn update if you have beeen away from your project for a while. In a multi user environment, you could be doing updates many times a day.
pgowda@3[sandbox]$ svn update
At revision 2.

Trunk, Branches and Tags

Earlier in the article, we created 3 sub folders namely trunk, branches and tags.Lets examine how this tree structure is useful in maintaining a software project throughout its lifetime.

Tools/GUI

I've only illustrated the use of command line use of Subversion here. However, there are excellent GUI tools which take away the burden (some would say, the power) of using the command line. RapidSVN and TortoiseSVN are two such tools. TortoiseSVN integrates into Windows Explorer and provides an easy to use interface. With TortoiseSVN instlled, files become colour coded to indicate their status (up to date, modified, in conflict), and most Subversion operations can be invoked using a simple right-click.

Summary

SVN is a mature and reliable Version Control system being widely used in many top-notch Open Source projects, typiclally supporting thousands of files and hundreds of commiters. We have seen how we can setup a working Subversion repository on a workstation and use the client. Yet, we have not covered how to use Subversion server (svnserve) and Subversion over the internet, as it is beyond the scope of this article. The possibilities are immense with a rich feature set and a world wide community of users and developers. For a complete reference of Subversion features and commands see http://svnbook.red-bean.com/. This book will answer most of the questions you may have on Subversion.

Resources

Pradeep Kishore Gowda is a Senior Software Engineer with ZeOmega,Bangalore; a company deeply commited Open Source Software development. He is a GNU/Linux user since 1997 and likes to program in Python,PHP and other dynamic languages. You can visit his blog at http://btbytes.com Email: [email protected]
Notes to the editor:
Author Name: Pradeep Kishore Gowda
Organisation: ZeOmega Infotech, Bangalore
Designation:Sr. Software Engineer,
Address:
#20, 2nd Floor,Rajalakshmi Plaza,
Southend road, Basavanagudi,
Bangalore, 560004
Phone: 80-26632589
Mobile: 9844514846
Photo: