Subversion (SVN) is a source code management system similar to CVS, but nicer in many ways. It assists with collaborative development, and can be useful even for single-developer projects where code may be modified on different computers.

Basic concepts

There are three main words you need to know, as it defines the primary ways that subversion organizes your code

• Trunk is where all your incremental versions are saved. Whenever you do a change and commit it, it is saved as a version in the Trunk. You can retrieve different versions. The trunk is meant to contain the branch of your code under active development. For example, lets say you already have a version 1 released to users, and you are developing version 2. You would save all the incremental (but perhaps unreleased to users) changes you make as you develop this 2nd version in the trunk.
• Tag is where you can store a self-contained snapshot of your code. Normally, you would do this to save (say) a version that was released to your end users. Tags are separate from trunks. For example, when Version 2 was done, you would save it as a tag.
• Branch is where you can store a version of your code that may differ from a version developed in the trunk (or another branch). For example, while developing version 2, you may be working on the main part of it (perhaps in the trunk, while someone else may be working on another part of it (as a branch). Afterwards, you can decide to merge the branch back into the trunk, but we won't discuss how to do that here.

To get started using Subversion:

1. E-mail bugzilla and ask them to grant your CPSC account permission to access the SVN repository for the ILab.
2. Download a subversion program to interface with the SVN repository. We recommend AnkhSVN, which integrates nicely with the Visual Studio IDE.

For reference, the ILab SVN repository URL is as follows: https://forge.cpsc.ucalgary.ca/svn/research/iLab/

The tutorial below illustrates the various steps using AnkhSVN and a 'Hello World' type of project, where different versions are indicated by the text in the window.

To create a new Solution and SVN Project:

1. When creating your project, check the "Add to Subversion" option at the bottom right
   
2. You'll see the following dialog box. Within it,
   • enter the iLab SVN repository URL: https://forge.cpsc.ucalgary.ca/svn/research/iLab/, which should display all the subfolders within it
   • create a folder for yourself off the "svn/research/ilab" root node, to store this and other projects e.g., for me it was saul.greenberg
   • check the Add trunk Folder for Project at the bottom, which will establish this project in your trunk.
   • You should get a message at the bottom saying where your project will be created. While you can change this, its probably best to leave it.
     
3. It will then raise another dialog box giving you the opportunity to create a log message detailing anything you've done. While you don't have to enter anything in the log, you'll find it handy as a way to add comments about your various versions. This will let you track things in the future.
   
4. Your solution explorer will now show the state of each of your files by icons added next to it. The + means that these files have not yet been added to the subversion, i.e., they still have to be committed.
   
5. To commit all un-added files, raise the context menu on the Solution in the Solution Explorer, and select Commit Solution Changes.
   • It will raise a dialog box giving you the opportunity to log a message
   • It will then display the actions it is taking on each file
   • All the icons will then turn into a checkmark, showing what is currently up to date in the repository
     
6. Alternately, if you already had an existing solution that was not in subversion, you can add it to SVN after the fact: raise the context menu on the Solution in the Solution Explorer, and select Add Solution to Subversion. Note that this menu option won't be displayed if the solution has already been added.
7. Congrats, your Solution is now under version control!

Ways of viewing your repository and its state.

Before going on to show you how to save and manipulate versions, you should know about the several ways you can view your repository and its state.

1. View in a web browser. There is nothing special about the repository. For example, if you point your browser to it (and enter your login name / password), it will let you navigate the file structure.
   
2. View in Repository Explorer. From the VS 2010 View menu, select Repository Explorer. This will raise the repository explorer, where you can navigate and inspect all the folders and files in the repository. The properties window will show the state of each selected file, e.g., its last committed date.
   
3. View in Pending Changes. Also from the VS 2010 View menu, select Pending Changes. This will raise the Pending Changes window (shown above) that displays all the files that have changed since this version was last committed, and gives you the option to select (or unselect) what files you actually want to commit. The above example lists nothing, simply because everything has been committed at this point.
4. Solution Explorer. As mentioned, the solution explorer adds icons next to each item managed by SVN, where icons indicate its state (see above, where the checkmarks indicate that all items are currently up to date in the repository). The context menus attached to each item also suggests what actions you can take on it given its current state.

Using the Trunk to save your ongoing work

As mentioned, the trunk is where you store snapshots (versions) of your solution as you are developing it. Its up to you to decide how often you do this. For this example, we will save two versions of our hello world program, where all we do is change the label in each version

1. Modify your solution. Change the label in your MainWindow.xaml file to read 'Version 1.0.1'. The fact that this file has changed from the last committed version is shown both in the pending changes view and in the icon view by the red checkmark.
   
2. Commit the Changes either by raising the context menu on your Solution and selecting Commit Solution Changes, or by selecting File-Subversion-Commit, or by selection 'Commit' from the Pending Changes window. Depending on the way you did this, you will have the opportunity to log a message as described previously.
3. Repeat the above by changing the label to 1.0.2.

How to Retrieve an earlier version

This can be done many ways. Here is one way.

1. From the Solution Explorer, raise the Solutions context menu and select Subversion-SwitchSolution
2. From the dialog box (below), change the Type to Revision and click the ... browse button
   
3. The Log Viewer displays the various versions in the trunk (you can now see the value of the log messages! I skipped one intentionally, which makes that entry somewhat mysterious). Select Version 1, which shows what actions had been done between that version and the initial version.
   
   • Your solution will now show (via the label text) that you are now displaying the original version 1.

Creating a Tag to save a snapshot of a specific version

As mentioned above, Tags are a way to save a complete snapshot of a version of your software. A typical use of a Tag is to save a version that is (say) a release or version update that you give to end users. While the trunk stores all your incremental work that is part of your routine development, a Tag is a good way to store a major version for later retrieval. The method used is almost identical to how you would create a Branch.

• Modify the Xaml file so the label reads Version 2 and commit it as normal to the trunk. We will save this version as well as a tag.
• Start the Save as Branch dialog. From the Solution Explorer, raise the Solutions context menu and select Subversion-BranchSolution....
• In the Url, change the path portion that reads branches to tag/<SOMENAME>, for example '''tag/Version2. Add log messages as desired. Note that you will have to rename this for every tag you save in the future - think of these as folders that would be otherwise overwritten (e.g., tag/Version3, etc).
  
• You can now, at any time, retrieve this version without going through the trunk.

To check out an existing SVN project from scratch

1. Start Visual Studio
2. Select File > Subversion > Open from Subversion
3. If the URL for your Subversion repository does not appear in the URL dropdown, then click the Add URL button beside it and type in the desired respository URL. You will be prompted for your username and password.
4. Browse to find the .SLN file of the desired solution you would like to check out. Select it and press the Open button. The "Open Project from Subversion" window appears.
5. In most cases you want the Type to be Latest Version. In the Local Directory group box, you can select where you want the files to go on your local machine. If you don't like the automatic suggestion, you can browse for a different location.
6. Click OK and wait for the project to download. The Solution will be opened and ready for you to stark working with it!

To obtain the latest version of your project

1. Use the Update button in the Pending Changes tool window, or right click on your solution and choose Update to Latest Version
2. Wait for the operation to complete.

Mixing Projects from Different SVN Repositories

You may wish to create your own solution which brings in one or more projects from a separate SVN solution. Furthermore, you may wish to put your own solution under version control. Luckily this works quite nicely because Visual Studio knows which projects belong to which SVN repositories. So if you add your solution to its own SVN repository, it will NOT include the sub-projects that are already under version control from other solutions. Furthermore, if you modify the projects from other repositories, your changes will automatically be committed to those subsequent repositories when you commit your solution.