Living In A Subversive World

This describes how to use Subversion on a day to day basis. If you have inherited or been assigned to a software development project that uses Subversion, but are unfamiliar with how it works and how to use it, then this post is for you.

So What is Subversion?

Apache Subversion is a Source Configuration Management (SCM) system that has one central repository, usually located on a web server. Each of us works on our own copy of the Subversion-controlled project. When post our changes back to the central repository, Subversion merges them with the existing code and increments the Revision number. Anyone who then updates their local copy of the project will now see the changes we just made. As long as everyone performs frequent updates to their local copy, it all works fine.

What’s So Great About It?

Subversion uses the copy-and-merge philosophy, in contrast with the Lock-Modify-Unlock method used by older SCMs such as RCS, and Microsoft Visual SourceSafe (VSS). In these systems, only one person can change a file at a time, while everyone else is locked out. Veterans of RCS or VSS may point to a risk of running into conflicts and other problems when using Subversion’s copy-and-merge. While the risk of conflicts is still present when two or more people are working on a file, in practice this is only a concern when these people are changing then same part of a file.

For example, suppose you and I are working on OurBigModule.java. You are working on lines 100 to 150, and I’ve made changes to lines 30 to 50. Just before I commit, I update my local copy of the project. Then I commit my changes to Subversion. When you have finished your changes you too update your local copy, but now Subversion merges the changes I made with your local copy. Now you are up to date with the central repository. You run the full suite of unit tests, they all pass, and you commit your changes to the central repository. The end result is the most recent version in the central repository has both mine and your changes in it.

Subversion really shines when it comes to committing changes. Unlike another of its predecessors – CVS (Concurrent Versioning System) – Subversion uses atomic commits. Say you have a dozen changed files to commit, and one of the file commits fails because of a conflict. Subversion will roll back the entire change set – all 12 files. You still have some work to do to resolve the conflict, but at least your repository is in a consistent state.

OK, How Do I Use Subversion?

1. Install a Subversion client on your local workstation. There are some fine plugins for Windows Explorer and Eclipse such as TortoiseSVN and Subclipse. For this post I’ll suggest using a command line client to help you understand what goes on under the covers with the graphical tools. CollabNet is the command line client I used.
2. Ensure the executables directory for your chosen SVN client is on your PATH environment variable.
3. Open a command line window, cd to wherever your workspace is and go:

   1. svn co http://svn.domain.com/bigproject/trunk bigproject

   2. This will create the directory bigproject in the current working directory, and check out the entire project into there.
   3. The URL is the Subversion repository. Your lead developer can supply this to you.
   4. “bigproject” is the fictitious name of our project in this example.
4. Write your unit tests. Make some code changes
5. Update your local copy with any changes others may have made: from the bigproject directory, go

   1. svn update

6. Make more code changes. Test and debug.
7. Now that all your changes are complete, prepare to commit them. First, do an svn update. If you see there were some changes merged in to your copy, run the full suite of unit tests to make sure they all pass.
8. Commit your changes:

   1. svn commit -m “A brief note to explain what you changed and why.”

Here are some other useful commands:

1. Are there any changes I haven’t committed?

   1. svn status

2. How do I delete a file and have Subversion know about it?

   1. svn delete src\java\com\domain\bigproject\OurObsoleteModule.java

   2. Subversion will record the delete when you do an svn commit.

Remember!

Everyone works on their own local copy of the source code. Don’t use a shared version that sits somewhere on a network drive and two or more people are working on it. Subversion is not designed to work that way. It would make it very difficult to figure out who changed what, your unfinished changes will get dragged along with my finished changes when I do a commit, it would just be a mess.

svn update often, at least once a day. I update first thing in the morning, and again right after lunch.

Only place textual source code files under version control. Libraries, JAR files, Word documents belong in different repositories such as Maven, Microsoft Sharepoint, Atlassian’s Confluence, MediaWiki, etc. Unlike text files, Subversion cannot show you why changed what with binary files.

Only commit working code to the trunk. The idea is we should be able to give a demo to our customers at any time by using what is in the trunk. Following this rule will improve your team’s code quality dramatically.

Want To Learn More?

We have just scratched the surface of Subversion. Your best resource is the Subversion Book. Read up on branching and tagging.