Setting up source control at home

If you are learning how to do development (or test automation) you need source control. I first spoke about this in So you want to create automated tests. Automated testing is software development and part of good software development is source control.

There are a number of open source projects you can use. Originally I would have been suggesting Concurrent Versions System (CVS). When you install something like Eclipse you will see it has the CVS plugin already installed. CVS is well over 20 years old and quite stable. However, Subversion (SVN) is another choice and one I'm going to talk about today.

SVN has been around for over 10 years. As of 3 days ago Subversion become Apache Subversion. The old official site was here. Now the official site is here. If you go to the old site you will find it directs you to the new site.

First thing we need to do is go to the new official site and download a copy of the binaries. SVN is supported on a wide variety of platforms including Linux, Mac OS X and Windows. You will need to download a server/client package. The SVN server will be installed on the machine hosting your files and the SVN client will be installed on the machine you want to do your development on (probably the same computer but you could work with a friend and have them host the server or put the server on a school computer).

Once you have downloaded and installed SVN you should be able to go to a command prompt and enter:

svn help

On a Mac OS X computer, go to Spotlight (upper right corner) and enter Terminal then select Terminal the application to get a command prompt. On a Windows computer, go to the Start->Run menu and enter cmd to get a command prompt.

Now on to creating your SVN repository. But first, a little bit about source control or Software Configuration Management (SCM). Files will exist in at least two locations. There is a repository and there is a working copy. The idea is that you create the files and copy the files to the repository (check in). You can then delete the files you created (working copy) because you have them backed up in the repository. You can make multiple copies of the files (check out) or you and a friend can each have your own copy of the files. First thing we need is a place to store the files or the repository.

We have to make a few decisions before we set up the repository. At some point you will probably have multiple projects. Do you want one repository for each project? Or do you want all the projects in one repository?

At first it will not matter but as you start using advance features it might. For example, at companies they might have a policy that no code change can be checked in to SVN unless you add a comment with the defect tracking system number. Thus to add a new feature to the project a developer must create an entry in the defect tracking system, create the feature and refer to the defect tracking number when they check in the work. SVN has triggers which allow us to remind the developer to do this. How they work is, when a developer tries to check in the code, SVN will scan the comments for a defect tracking number. If there is no number it will reject the check in and ask the developer to include the number in the comments. Do you want this for all the projects you set up? Or only some? If you have one repository, rules like this apply to all projects. If you have multiple repositories then each can have its own set of rules.

For now, lets assume you are just working on one project but leave room for more projects in the same repository. If you change your mind, you can create another repository later.

Select a computer to host the repository (localhost probably) and a location on the file system (on Mac OS X, Linux, UNIX you can use maybe /var/svn/repos; on Windows you can use C:\var\svn\repos). I'll refer to this location at the SVN repository root.

When selecting a computer to host the files on you have to consider things like who will be accessing it and how. If you were setting up a repository for a company and had to deal with firewalls, proxies, user security, etc. it would be an entire chapter in a book. However, this is just a personal repository for you to start learning at home.

Now that we know where the files are going to live we need to decide if we want to store the files in the file system or a Berkeley database. Using a Berkeley DB is more reliable for day to day operations but more work to setup and administer. There have been some bugs relating to using the file system but for our purposes I think it will be fine. Additionally, using the file system is the default since SVN 1.2. So the file system it is.

So, assuming the repository is going into /svn/repositories, lets create a repository for Selenium testing and we'll call it the SELTEST project. From the command prompt:

svnadmin create /var/svn/repos/SELTEST

And that is it. If you look in the directory /var/svn/repos/SELTEST you should find something like:

-rw-r--r--   1 darrell  darrell  229 20 Feb 10:06 README.txt
drwxr-xr-x   5 darrell  darrell  170 20 Feb 10:06 conf
drwxr-xr-x   2 darrell  darrell   68 20 Feb 10:06 dav
drwxr-sr-x  10 darrell  darrell  340 20 Feb 10:06 db
-r--r--r--   1 darrell  darrell    2 20 Feb 10:06 format
drwxr-xr-x  11 darrell  darrell  374 20 Feb 10:06 hooks
drwxr-xr-x   4 darrell  darrell  136 20 Feb 10:06 locks

but you want to access these files using the svn command. On UNIX/Linux/Mac OS X you can use the file system directory permissions to control access. Create groups and use the chmod, chgrp commands.

At this point you are ready to start using SVN. If at a later date you decide you want things setup differently, no problem. There are instructions on migrating, updating, backing up, renaming, etc. your SVN repositories. For now, let's start checking in some code.

Let's assume we are using Eclipse and want to access our SVN repository. Eclipse comes with a plugin for CVS but you'll have to add one for SVN. I recommend using subclipse. There are other SVN client plugins for Eclipse but I have been extremely happy with subclipse. Assuming you already have Eclipse installed and running:

• Go to the subclipse web site
• Go to the download and install section
• Find the update link for your version of Eclipse
• Copy the link and go to Eclipse
• Select the Install Software... menu option (usually in the Help menu)
• When this dialog open you can add the subclipse link
• There should be 3 parts to subclipse
• Select all of them and click Next
• Follow the wizard and accept the license agreement
• You may get a warning about unsigned content
• I accept the installation anyway
• Once it is done you'll have to restart Eclipse
• Now you can switch to the SVN perspective
• Go to the Window menu and open a perspective
• You'll have to select Other... and find the SVN Repository Exploring perspective
• In this perspective there will be a SVN Repositories tab (upper left corner)
• Right click in there and select New->Repository Location...

Now assuming the files are on the local file system, the SVN URL will start with file: but if you are accessing the files from a remote computer you'll need to use ssh. We assume that ssh is set up on the remote computer and you have a login. For a remote computer you want svn+ssh: protocol.

Let's assume the files are located cs.toronto.edu, the repository root is at /u/dgrainge/svn/repos/SELTEST and I can log in with dgrainge. The URL is going to be:

svn+ssh://cs.toronto.edu/u/dgrainge/svn/repos/SELTEST

When I enter this into Eclipse it will ask me for my username and password. These are the username and password I use when I ssh to cs.toronto.edu.

If I am going to be hosting the repository locally in /var/svn/repos/SELTEST then I would use:

file:///var/svn/repos/SELTEST

Because it is local there is no need for a username or password.

Once the repository has been added to Eclipse I can switch back to the Java perspective. Assuming I already have a Java project I want to add to SVN:

• Right click on the Project Name in Package Explorer
• Go down to Team and select Share Project
• Select SVN for the type of repository to use then click Next
• Select the existing repository we just created and click Next
• Click Next to accept the default URL
• Click Finish to start copying the project to the repository
• It will ask you for an 'author' name
• This just identified that you want to check the project into SVN
• Now we have to pick which files to commit (copy)

We do not want to add things like .project, .classpath or .setting. In the Synchronize view:

• Right click on .project and select Add to svn:ignore
• Right click on .classpath and select Add to svn:ignore
• Right click on the root of the project and select Commit
• A list of files to copy to SVN will be listed
• If any of the files are generated (.class files) you don't want to add them
• Any log files or output from running the project should not be added
• Uncheck everything you don't want to add to the repository
• Put the comment in "Initial check in"
• Click OK

If you check in too much you can always remove it later. If you fail to check something in then delete the local copy, it is gone forever.

Next blog entry will be about using the repository and all the benefits it gives you.