Worry free development: An SVN tutorial for single developers

This guide will (hopefully) enlighten you to the benefits of using a Source Control system in your development, even if you are a hobbyist working on small projects. After a 5 minute free installation you will be able to save a snapshot of your project with a single click, allowing you to modify the code knowing you can revert your changes to any state at any time.

Working as a single programmer on a project has its benefits – no one tramples your code, you can modify any module you wish at any time and as long as you keep your standards, the project will always compile. As the team grows bigger and the project becomes mission critical, many problems arise:

• Two or more programmers work on the same module – how do they share?
• Bugs in a certain version pop up that did not exist in previous, seemingly unaffected, versions. What has changed between the two versions and when?
• Customer A has received version 1, while development has reached version 20. Customer A is happy but finds a bug – do you update him to version 20 or fix this specific bug on version 1? If so, how do you find manage the source code for each customer?

Source Control, in a nutshell

---

Source Control systems were devised to help with the above and much much more. Commercial grade examples include cvs, svn, ClearCase, Perforce, SourceSafe and many others. They all share the same basic architecture: A single server contains a change-based repository of your projects while distributed clients (which reside on the programmers machine) allow the programmer to access code on the repository for either applying his changes to the repository (what is usually called “checking in” or “committing”) or by synchronizing to the changes made to the project by others (“updating”, “syncing to latest” and sometimes “checking out”).
There are many guides to working with a Source Control system on the web and i won’t dive into its theory of operation in a team environment. I will, however, offer a simple and free way of using Source Control in your project, even if you are a hobbyist developing stuff in your spare time.

I’m a single developer – Why should I care?

---

As a single developer, you gain one huge advantage of using Source Control – the ability to save the state of your project at any time, with a single click. This allows you to easily revert any changes you have made and make all manual backups of source redundant. Even if you are slightly modifying your code – and you know that the code works in its current state – save a snapshot. You will feel so confident changing the code because you know that at a click of a button you will be able to revert your changes to any previous working state.
What to install:

• The server: VisualSVN (You can use this tutorial for installation – but basically you just click next a bunch of times)
• The client: TortoiseSVN

Keep in mind that you can install both the client and server on the same machine or put the server on a different machine,. The server does not take any resources during normal operation, but it may be beneficiary to do so for safety reasons (if someone steals/hacks into/destroys your client machine, your code is still safe at the server). After installing VisualSVN, follow the tutorial above to create a repository. A repository is, in essence, just a directory that holds versions of any files you give it – it is up to you to decide how the repository looks like and how many projects (or project) it contains. Thankfully, we don’t have to think too hard as there is a logical standard for this: simply create a repository per project, naming the repository after the project. When you create a repository, you are allowed the option of letting VisualSVN create a default sub structure for it. This is optional, but is recommended as this sub structure is well known and intuitive to most programmers working with SVN. This substructure contains:

• trunk: The place where ongoing development goes on. You copy your initial code here and always check your changes in to this single location. The trunk will hold the entire history of your project and will be the location you should take the source from should you want the most up to date, compiling, unstable version.
• tags: When the trunk reaches a certain milestone (say you validated all your modules), you would probably like to take a snapshot of this trunk. To do this, you simply copy it to a new sub directory in tags (effectively tagging it). For example, if your trunk version has reached version 0.2.0, create a subdirectory called 0.2.0 in tags and copy the trunk to it. You should never modify (check in) code in the tags sub folder – the whole point of a tag is to save the program’s state at a given point in time.
• branches: This is a lesser used functionality and is mostly intended for larger projects with a longer lifetime and several programmers. If, for example, you would like to add a certain functionality to your source but would like this NOT to be a part of the main trunk, for whatever reason (could be that you do not want to introduce risk to the trunk, on which several programmers are working on but still would like to source control your work) – you would create a branch off of the trunk and work there.

All of the above are not “special” sub folders and do not behave differently as far as SVN is concerned. You can choose not to follow this recommendation and find a sub structure that works for you.

Working with SVN

---

Once you settled on a sub structure for your repository (and I sincerely hope you opt to use the standard trunk/tags/branches) you need to upload your current source code to the trunk (or equivalent). This is done at the client machine using TortoiseSVN. TortoiseSVN is a shell extension – that is to say, all of its functionality is accessed via File Explorer. To do this, you simply need to right click on your project directory, select TortoiseSvn -> Import and set the URL to:

• https://[server-ip]:8443/svn/[repository-name]/trunk

This will effectively upload your source code (and any files that are not filtered out) to the repository’s trunk. Note that you should clean up your project from all intermediate files before you import, as there is no requirement to version/backup these files. Your source code is now compressed inside the repository, waiting to receive updates. For reasons beyond me, importing the source code does not actually link your local code with that of the just uploaded repository. You must do this manually by creating a working copy.

A working copy is the copy of the code on your local hard drive.Yes, you just imported the source and therefore it must already be on your drive, but you still need to perform this step. Right click on a directory you want your working copy to reside in (usually, it will be where your original non-source controlled version was located – so you will probably need to move that somewhere – you can even safely delete it) and select TortoiseSVN -> Checkout. Select the same URL you imported to (ending with trunk) and watch how the source is copied from the repository. You will see that the new working copy has some green icons next to each file name and directory (). This indicates that the file is up-to-date with the file in the repository. Go ahead and modify a file – you will see that it’s icon has changed to red (). If you would like to commit this file (that is, upload the changes you just made to the repository), you can right click on it and select TortoiseSVN -> Commit. Better yet, you can right click on the project directory and select Commit – all modified files will be sent to the repository. Remember that committing changes does not override the repository contents – the repository will always remember the state of the files at any previous state. In the previous example, we would have two versions of the modified file: the first, initial version which was created when we imported the project and a second version which we just created by committing our changes. At any time we can revert to either of these versions, regardless of how many commits we perform on this file.

This is where the magic happens – every time you go about changing your code, simply commit the changes to the project. At this point you are safe to change your code knowing that the code is safely versioned in the repository.

Reverting changes and viewing differences

---

Should you decide that you would like to  revert your changes you can do this by Right clicking on the file (or files) you want to revert and either:

• Select SVN Update. This will simply copy the file version in the selected repository sub directory (usually trunk)
• Selecting TortoiseSVN ->Diff. This will let you diff your working copy with that in the repository
• Selecting TortoiseSVN -> Show log. This will show you a revision log of the file and allow you to view differences between your working copy and any revision, and between any revision to any revision

Summary: Using SVN, from scratch

---

Let’s recap:

• Step 1: Install VisualSVN and TortoiseSVN
• Step 2: Create a repository and a tags/trunk/branch sub structure
• Step 3: Import your project to the repository
• Step 4: Create working copy of your project by deleting the project from its local dir and checking out the trunk
• Step 5: Whenever you are going to change the source to add a functionality of some sort, right click on the project directory and choose “Commit”
• Step 6: Should you ever choose to revert your changes, use one of the methods described above

For further reading, see the fantastically written TortoiseSVN help file.