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:
- Track changes to your code over time. Compare what changes have been to the code
- Manage multiple copies of same base code which are tweaked for different installation instances
- If you have bungled up the code, you can safely roll back to the version which was working.
- Save disk space by only saving the changes and not making replicates of the whole project.
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.txtThats 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.phpImport 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.phpYour 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.phpLets 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.phpWhat 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.phpThats because svn does not recognise funcs.php, yet. To add this file to the repository:
pgowda@3[sandbox]$ svn add funcs.php A funcs.phpOther 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.
- Trunk: Trunk is you main working copy. The stable branch. Dont put broken code here. If you are deviating a lot from the trunk, better fork out a branch and do the experiements there.
- Branches : Copies of the trunk where some files would be changed drastically so as to be maintained sepertely. But, this does not mean a literal copy of the trunk. Only the changed files will be stored in the trunk. If are doing a customisation of your software 'Super Widget' fo 'Acme Inc.', you will want to store the modified files under Acme.
pgowda@3[sandbox]$svn copy file:///home/pgowda/repos/project1/trunk \ file:///home/pgowda/repos/project1/braches/acme -m "Creating a copy of Superwidget customisations for Acme Inc"
pgowda@3[sandbox]$svn copy file:///home/pgowda/repos/project1/trunk \ file:///home/pgowda/repos/project1/tags/LifeSaver-1.0 -m "Tagging the 1.0 release of the LifeSaver Project"
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
- http://subversion.tigris.org/
- http://tortoisesvn.tigris.org/
- http://rapidsvn.tigris.org/
- http://svnbook.red-bean.com/