Getting started with Source Control

Source control software is one of the most important tools in the repertoire of a programmer. Learning to use it will greatly improve you efficiency as a team working on a project.

So who needs to use source control?

If you’re working on a project with more than one member, you should use source control. Also if you work alone, source control can be very useful, since it helps backing up multiple versions of your codebase, in case you accidentally lose your code, change something and later realize that the previous solution was better. Even when you need to work on multiple systems, like a desktop computer and a laptop and don’t want to carry it around in a USB stick, source control can help you with that.

So what is source control?

Source control is a way for people to simultaneously work on the same codebase. It needs to make sure every developer on the team has access to the most recent version of the codebase and makes sure merging the works of the different developers works as painlessly as possible.

For example: Take two people working on the same project. They each work on the project on their own, but eventually they need to put their works together. How should they do that? Usually they will have changed existing files and created new ones, both developers may even have changed the same file. This all needs to be put together, and source control helps you with that!

Cool, I want source control!

Well, source control isn’t a particular program or a specific software, it’s just refers to the type of programs (just like web servers etc.) The source control software that we’re going to use is called Subversion (or SVN). It works with a server/client architecture. You need to have some place to host your code, to act as the server. You can do this yourself by downloading Subversion server software and host your code on your own machine, but I’d recommend you to use a third party hosting. This way, you don’t have to manage the server (and keep a machine running all day long) yourself.

There are quite a few free Subversion hosting solutions available on the web, for example: Google Code and SourceForge. These are good places to host your code, but they require you to make your code public. This isn´t always ideal for your project, so I’d prefer to use a hosting solution that gives you the choice whether you want to publish your code or not.

The best free closed-source hosting solution I found so far is Assembla. It gives you pretty much everything you need for free. There are some premium tools that you can pay for, for example tickets, a wiki etc., but you probably don’t need them. So the server part of the problem is solved: We’ll use Assembla to host our project.

How do I create my source control repository (and what’s a repository?)

The repository is a place where your codebase resides. In case of Subversion, it’s some place in the server. The repository does not only contain the current state of the codebase, but also all the changes (so previous versions).

Step one: Create an Assembla account. Just head over to http://www.assembla.com/ , click register and fill out the form.

Step two: Create a free subversion space. To do this, go to http://www.assembla.com/catalog and click on the gray bar at the bottom saying: “We also have some limited free options where you can’t add extra tools”. This will expand a few other, free, repository options. Select “Free Subversion Repository – Commercial Quality”, fill out the form and click on “Create the Space”.

You should see something that looks like this:

Here, you can give people access to your repository, change some settings, and most importantly, get the SVN URL. You’ll need this to access your repository with the SVN client.

SVN actions

Before we delve into the specific application, let’s discuss a few common actions that you’ll use when using source control in general and Subversion in particular.

Checkout – Checkout takes a folder (usually an empty one) and “links” it to the repository on the server. You’ll need to provide your repository URL, username and password when checking out a folder. The client will then download the latest version of the repository and generate some other management files, only to be read and modified by the svn client. These files are stored in folders called .svn. These are invisible by default, but you can see them if you change your folder settings. Do not modify or delete these folders or the files inside. We’ll call the folder that you checked out the workspace.

Update – Updating the workspace retrieves the latest version of the repository from the server. If you had changed some files, it will try to merge these files. This doesn’t always succeed automatically, manual merging is sometimes required. I´ll explain merging later in more detail.

Commit – When you’ve implemented a feature in your project and your project compiles and works again, it’s a good time to commit your work. Committing sends the changes you made to your workspace to the repository. This is only possible if the version of your workspace had the latest version. That means no one committed their work in the time between your last update and your commit. If you don’t have the latest version, then you’ll have to update first. This will again require a few files to be merged, automatically or manually. Every time you commit, you can add a message to it so your teammates can quickly see what you did/implemented.

Ignore – Whenever you commit you work, you need to select which files to commit and which not. In a dialog box, there will be a list of all the files that have been changed that you can select to commit. However, you shouldn’t commit files that have been generated by the compiler, since these usually are big, change often and can be recreated anyway. You can ignore these files, so they don’t show up in the dialog box to select to commit. A good rule of thumb is to not commit any files where there is a “bin” or “obj” in the file path. You only have to ignore files once, SVN will remember their name and ignore them, even when they’re deleted and recreated.

If you’re using Visual Studio, then you can also ignore the .suo file, this file contains the user settings like which files were opened since the last time you closed Visual Studio. These are different for everyone and change often, so don’t commit it.

Export – When you’re done developing your project, you probably want to publish some files from your repository (like the latest build) If you just copy/paste the files/folders that you want to publish, you’ll also copy those .svn folders and the files inside. The export action exports a file or folder from your repository to some location on your hard disk without those .svn folders.

TortoiseSVN

In this guide we’re going to use a program called TortoiseSVN (You can get it at http://tortoisesvn.tigris.org/ ) It’s only available on Windows. There are lots of SVN client programs, also for Mac and Linux. The actions are called the same, I’m sure you can figure it out. TortoiseSVN is a program that adds a few items to your shell extension (right click menu) This is actually the only way to access the program.

When you right click an empty folder, you can choose SVN checkout and it will perform the checkout action. A dialog will pop up asking for your username password  and the URL to your repository and you’ll see the status of the files downloading from the repository.

After you´ve checked out a folder, its icon will change indicating the status of the folder (changed, up to date etc) Also all the files inside your workspace will have changed icons. When you right click on your workspace or anywhere inside your workspace, you’ll see a few extra SVN options have appeared including commit and update.

You actually don’t need to update and commit your whole workspace, you can also just right click on a folder somewhere inside your workspace and perform SVN actions on them like deleting, ignoring, updating and committing.

That´s about it about the program. If you´re having difficulties with it, just post them in the comments. Also, don’t rely too much on the icons indicating the status of a file (up to date etc.) since these icons often aren’t up to date.

Merging conflicted files.

Whenever you and someone else on your team modify the same file and want to commit it to the repository, one of you will be lucky. He’ll commit first, and you’ll have to update your workspace before committing. When you update your workspace, you’ll get a conflict. If you two were working on different parts of the same file, it will automatically be merged and the conflict will be resolved. But if the same lines were changed, you’ll have to do it manually. You’ll be presented with the two different versions and you’ll have to choose which version of the lines (or methods) needs to be in the final file.

TortoiseSVN has a default merging tool (TortoiseMerge), but you can also use third-party tools for merging.

In the update window, you’ll see the conflicted files. Right click on them and choose merge.

When merging you’ll see three screens, one with your version of the file, one with the version from the repository and one with the final version. You’ll see blocks of code where there is a conflict and you’ll have to choose one of them for the final version. This usually involves right clicking and choosing which piece of code you want, but some programs have arrows or other kinds of icons that you can click indicate your choice. After you’ve handled the conflict, save the work and close the merging program.

Then right click on the file you just merged and select mark as resolved. And do the same with the next conflict.

Good practices to stay out of trouble.

Here are some tips that will save you time and conflicts with SVN:

In order to minimize the times that you’ll need to merge files, it’s good practice to first update the repository before starting to make changes to the project. Also, keep your commit periods (the time between starting to edit the project and committing) as short as possible. When you’ve implemented one feature and it works, just commit it. Put the next feature in another commit. If you’re working on a big feature that can’t be implemented within in a few hours, split up the work into chunks. Usually you need to add a few new classes then or add a few new methods. You can add these without changing the actual application, since those methods aren’t called yet. So add a few methods or a class and commit when you think it’s a good time.

Whatever you do, do not commit a project that doesn’t compile or that crashes often (like on startup). Also when you have to update before committing, update, test whether the project still works, then commit.

Close Visual Studio (or any other IDE) before committing your project. The project files usually aren’t saved when you compile or save your source code. Closing the IDE usually asks you if you want to save your changes to the project whenever you’ve added a file or changed a project setting for example.

Close your IDE before updating.

Whenever you add files to your project, try to do this as quickly as possible and commit with empty files, edit them later. Adding files to your project changes your project file and this file needs to be committed too, and it almost always requires a manual merge, since it’s very likely that the project file will be modified by another person (who’s also adding a new file to the project)

When committing, double check the files you’ve selected to commit. Especially when you’ve added new files, these aren’t selected automatically, you’ll need to check their boxes by yourself.

Whenever deleting a complete folder, use the SVN delete feature instead of just deleting it.

Write useful commit messages when committing. It’s also very useful when you need to keep a logbook, you can just check the commits messages and get an overview of the development process.

That´s it!

You now know how to use source control with subversion using TortoiseSVN.

Quick steps for starting a new project using SVN: Create new space (repository) in Assembla -> Add team members -> Create an empty folder somewhere on your hard disk -> Checkout the folder -> Create project inside the trunk folder in your workspace -> Commit

Quick steps to move an existing project to SVN: Create new space (repository) in Assembla -> Add team members -> Create an empty folder somewhere on your hard disk -> Checkout the folder -> Move your current project files to the trunk folder in your workspace -> Commit

And when committing, don’t forget to ignore intermediate files and check all the files that actually are needed.

Thank you for reading this article, I hope this will save some pain and suffering on your future projects.

If you have any questions or remarks, please write them in the comments or mail me.