Setting Up and Running Subversion and Tortoise SVN with Visual Studio and .NET

Source control is an important aspect in software development even if you are not doing team development.

It can help you manage your application more efficiently and make sure that your project is backed up and can be rolled back to any revision on the file or project level. I recently got acquainted with the open source Subversion and Tortoise SVN tools and, for the first time, feel that this is source control that I can live with comfortably. This article describes all you need to know to get started with Subversion and Tortoise SVN for Visual Studio projects.

This article describes the steps to install and configure the Subversion source control tool and walks you through the basic steps required to set up local Visual Studio projects using Tortoise SVN.

Subversion typically runs as a Service either using TCP/IP or HTTP, the latter of which requires Apache.

This article isn’t meant to be a comprehensive tutorial on Subversion, but rather a quick, what-you-need-to-know, step-by-step guide to the essential tools to install and configure to get up and running.

What Is Subversion?

Subversion is an open source control repository tool. It is widely used by many open source projects and increasingly by many large development teams in general. It’s fast and efficient, small and easy to install and because it’s open source-it’s also free. Subversion is file based and keeps its repository in a simple directory structure that you can copy and back up easily.

You can graphically access Subversion via Tortoise SVN, which is an Explorer Shell Extension that provides access to most of Subversion’s command-line interface through Explorer Context menus and overlay icons for files under source control. This actually is very powerful as it lets you use a familiar Explorer interface as your source code browser and, more importantly, because it very easily lets you see source control files in relation to the actual directory structure and what is and isn’t under source control.

Subversion subscribes to the Copy-Modify-Merge philosophy of source control, which means that files are never locked and nobody ever “owns” a file. Rather Subversion manages changes by merging source files with any changes made and only notifies you of conflicts if there are changes that cannot be merged (i.e., changes to the same line of code typically).

Coming from a background of using integrated security in Visual Studio, I at first had my doubts about the merge approach. However, I’m finding that it allows considerably smoother development as you don’t have to worry about constant check-out/check-in scenarios and locking files for other users. Instead you simply work on your code and when you’re done you can check in all changes using Tortoise SVN. Not having source control inside of Visual Studio may sound like blasphemy if you’ve used Visual SourceSafe, Vault, or another source code control provider before. I was skeptical about lacking Visual Studio integration when I started out, but I find I really don’t miss the integration with Visual Studio. More importantly, I don’t miss the problems that go with integrated source control in Visual Studio with the provider manager often getting confused, especially in complex Visual Studio Solutions and shared project scenarios. Subversion has actually made many scenarios that used to royally suck and required constant fiddling with Visual Studio and the source providers much easier.

Subversion is based on a file system tracking mechanism, so it is essentially tool agnostic. In fact, I use Subversion now with my .NET projects as well as with my old FoxPro projects-the process is no different, which is great for consistency and allows storage of all sorts of files from documentation to support files that otherwise wouldn’t be part of a Visual Studio project.

Installation

To start, download Subversion and Tortoise SVN and install both.

You can download Subversion from here: http://subversion.tigris.org/

You can download Tortoise SVN from here: http://tortoisesvn.tigris.org/

If you want Visual Studio integration, check out VisualSVN ($49) or the free Ankh tool:

http://www.VisualSvn.com/

http://ankhsvn.tigris.org/

Start by installing Subversion, and then install Tortoise SVN. Tortoise works as a front-end UI to Subversion. Both need to be compatible, so you should always install the latest version of each.

I’ll walk you through the process of creating a new repository and adding a Visual Studio Solution with a couple of projects to it.

If you are not setting up a new repository and just need to create a local copy from Subversion repository, just skip ahead to the Creating a Local Copy section.

Configuration for Tortoise SVN

Before doing anything else, I suggest you make one small configuration change in Tortoise SVN-change the name of the local svn repositories from .svn to _svn.

Make sure you’ve installed Tortoise SVN. Go into Explorer and right-click anywhere on a file or folder. On the shortcut menu, choose TortoiseSVN and choose Settings and check the “Use ‘_svn’ instead of ‘.svn’” check box on the General tab as shown in Figure 1.

Visual Studio has issues with folders that start with a period so it’s best to use the _svn prefix, especially if you decide later on to use a tool that integrates with Visual Studio.

Create a New Repository with Tortoise SVN

Now you’re ready to create a new repository. The repository is a storage location on disk where all the versioned data is stored. You can store the repository on your local machine or a remote server where users can access it either through the Subversion Daemon service or through HTTP via an Apache module (separate install). The key is that you need to be able to create the repository on that machine.

Tortoise SVN is a GUI front to Subversion that runs as an Explorer shell extension.

To create a repository, create a main folder for your main Subversion repository. I prefer to use a top-level folder so it’s easy to find and back up. So choose something like d:\subversion and do the following:

1. Create Folder d:\subversion.
2. Right-click TortoiseSVN and choose Create repository here.
3. Set up permissions for this repository.

To set up permissions, you need to configure d:\subversion\conf\svnserve.conf and password.

In SvnServe.conf:

[general]
# anon-access = read
auth-access = write
password-db = passwd
realm = SummaLp

This enables only authenticated access to the repository and provides write access for authenticated users and no access for anonymous users.

Next edit the password file (password with no extension) and add any names you want to allow as key value pairs. For example:

[users]
ricks = wonkiewind
billp = haggard

Setting Up to Run Subversion as a Service

With the repository created, the next step is to make it accessible remotely. Subversion comes with a built-in Daemon server that can serve your repository data over a TCP/IP connection (port 3690 by default). Alternately you can use Apache and an Apache module to connect to the repository over HTTP. The TCP/IP service is native to Subversion and is easiest to set up. It’s also faster than the HTTP integration. HTTP runs through Apache and offers better security and authentication as well as access through port 80.

I’ll only describe how to use the TCP/IP Daemon service here. The service is provided by SvnServe.exe in the BIN directory of the Subversion installation. While you can run the .exe file explicitly to start the server you’ll definitely want to install it as a service. To do this you can run the following command line (I suggest putting it in a batch file-all on one line!):

sc create svn binpath= "\"c:\program
 files\subversion\bin\svnserve.exe\"
 --service -rd:\subversion"
    displayname= "Subversion Server"
    depend= Tcpip start= auto

You should ensure that the paths in this command line match your installation and repository paths. Also note the spaces in the command line! They are not optional-I had trouble getting things to work until the spaces were added.

If you want to use a different port add: listen-port=nn for the port ID. Check for other options in the documentation.

Next you need to start the service through the Service Manager or from the command prompt:

sc start svn

You should only have to do this once-if you installed the service with the command above the service should auto-start next time you start Windows.

Check the Repository

Next you should make sure the repository works. To do this, fire up Tortoise SVN from anywhere and try to connect to your IP address or host name. Simply open Explorer, right-click, and from the shortcut menu choose TortoiseSVN and then choose Repo-browser. Type in svn://<youripaddress|hostname>/ and you should land at your repository. If you installed the repository on a remote machine, use its IP address or domain name.

Open the repository by double-clicking the node and ensure you don’t get an error message-if you do the repository is not accessible. If you opened the repository from a local machine, this should definitely work. If it doesn’t, make sure your repository and the path specified for the service start up match! On a remote repository, make sure that the port the server is running on is open in your firewall and your server’s firewall. The default port is 3690.

And voilà you are now set up for shared source control with Subversion.

Adding Projects and Files to Source Control

Now you’ll actually add Visual Studio projects to source control. As mentioned, Tortoise SVN doesn’t use any Visual Studio integration; it manages source control at the directory and file level. Basically, you can add any file or directory to source control, which means you can use Subversion with any type of tool that has files related to it.

Now you’ll decide how to lay out the repository. If you have many projects, it’s probably a good idea to have a layout that groups things nicely. I like to use:

Repository
-- ProjectGroup1 (ie. Solution level)
----Project
----Project
----Project
----Project
-- ProjectGroup2 (ie. Solution Level)
----Project
----Project

But that’s entirely up to you. I like a separate “Project Group/Solution” type folder so I can use it to hold Solution files and as a “header” folder that serves as a grouping for the subprojects. Otherwise it’s too easy to end up with a deep mess of project level folders.

So for the examples here I’ll use a starting folder structure of:

Repository
-- SummaLp
---- SummaLpManager
---- SummaLpBusiness
---- SupportAssemblies

Creating a New Top-level Folder

Creating projects is a little bit convoluted with Tortoise, because while you can easily import content into SVN on the server, an import doesn’t automatically check out the content locally. You also can’t immediately check out after you’ve imported because Tortoise will not allow you to overwrite existing files that are not under source control. I advise that you do not use the Import feature, but rather create a directory in the repository without any files, check out the folder, and then manually add files and subfolders.

Keeping checkouts as short as possible ensures the fewest possible conflicts.

For this example, create a top-level folder named SummaLp as shown in Figure 2 and Figure 3.

1. Go into TortoiseSVN and select Repo Browser (right-click, choose Tortoise, choose Repo Browser).
2. Use the Create Folder option to create a new top-level folder just beneath the main repository (name it SummaLp).
3. Go back to Explorer and go to or create a SummaLp Folder.
4. Right-click the folder and select Checkout… as shown in Figure 4.
5. Select the top-level folder in the repository and point at the corresponding local path as shown in Figure 5.

This puts the root folder under source control so you can now add individual files or other folders more easily. Nothing’s really checked out yet-this only marks the folder for being watched by Subversion. Go back to Explorer and check the folder-it should have a green icon with it now (Figure 6).

Don’t just start importing everything below in one pop-it’ll be much easier to create the project folders in the repository first-and then add the individual files once the folder is under source control.

Select one of the project folders and basically follow the same routine as above.

1. Go into Tortoise and browse to your repository.
2. Create a folder with the project name below the SummaLp folder (SummaLpManager).
3. Go into Explorer and check out into the corresponding folder. This puts the project folder under source control.
4. Select files and folders, right-click, and then add as shown in Figure 7.

Be selective and if necessary, add files individually rather than full subfolders. You’ll want to skip over things like the obj folder, notes, suo, .user files, log files, and anything that you don’t want tracked.

You’ll see a directory full of files with + signs next to them after adding. This means the files have been added to the local store but not synched with the server.

5. To sync with the server, right-click and select SVN Commit on the project folder as shown in Figure 8.

This basically tries to synch all the local changes to the server and, in this case, copies the files to the server and into the repository. If there are any conflicts-changes made to a file that can’t be automatically merged-the entire update fails and notifies you. Commit is an all or nothing operation-all files have to pass or the “commit” is aborted. If there’s a conflict, you have to resolve the conflict before you can check the file in.

Once you’ve done this, your local copy should now be up to date, as shown in Figure 9. Your repository is now synched.

The repositiory will now hold the same set of files as your local folder with “controlled” files. Figure 10 shows the Repo Browser view. Repeat this process for each of the other project folders.

You’ll also want to add the Solution file to source control. Just Add and Commit if it wasn’t among the files you already checked in. It’s best to have the solution file in the root branch (SummaLP in the example) to ensure pathing is properly relative.

Review

The repository is now set up and ready for shared use. The key thing to remember when creating new branches and adding new files in the repository is:

• Create a folder in the repository first.
• Check out just the folder to your local folder.
• Add files with Tortoise in Explorer.
• Commit changes.

Creating a Local Copy from the Repository

What I’ve described above is a bit of work but it only needs to happen once when you first create the repository. If you are a developer who’s simply connecting to get the latest revision for a local copy down to a local machine for the first time, the process is much easier:

1. Pick a directory where you would like to create the local copy.
2. Right-click and choose SVN Checkout… as shown in Figure 4.
3. Open the repository, set the project folder in the repository, and then provide the local folder path that will receive the checked out files. In the example above, you choose SummaLp (the top-level folder) and Checkout to bring down the entire project with the Solution file ready to go.

Post Setup Cleanup

Remember that once you have downloaded the project to your local machine, you may still have to configure your project properly. If you’re dealing with an ASP.NET Web application, you may have to register a virtual directory and set directory permissions or add scriptmaps, etc.

VisualSVN integrates with Visual Studio, but uses Tortoise for most of its UI.

Also depending on how well you set up the repository, you may be missing some project dependencies. One very important thing to remember is to make it as easy as possible to get access to any support assemblies required for the project by other users. I tend to create a SupportAssemblies folder in the repository with each solution that holds all non-project assemblies that might be required by the project. I bind to those assemblies in each project to ensure that all developers are working with the same version of external assemblies.

With components in the GAC, this can be more tricky-in that case each user must ensure they have the appropriate components registered on their machine. If possible (and if licensing allows), I still distribute any controls in the SupportAssemblies folder to make sure other developers can get up and running. It’s a good idea to document any dependencies and provide a Readme file with the project.

Up and Running with Tortoise and Subversion

You’re now set up for source control. Remember that Subversion uses Copy-Modify-Merge style, which means that files are never locked (unless you explicitly do so) and you can freely change source files.

For general operation you can simply edit files and Subversion will keep track of the changes for you. You can use Tortoise SVN in Explorer any time to see any changes that have been made to files. Any changed files will show with a red warning icon, which means you’ve made changes to the file that haven’t been updated onto the server.

The red icons appear next to files as well as folders. If there’s a folder that has unsubmitted changes, that folder will recursively show the red icon. Note that the red icon does not tell you whether the file has been changed by anybody else! It only tells you that you have changed the file and need to commit it.

To update your changes to the Subversion server, you use the SVN Commit option to synch with the server as shown in Figure 8.

You’ll get a dialog box (shown in Figure 11) that lets you quickly see all the files that are going to be updated by the commit operation. You can also selectively clear files, which is useful if you have one or two files that you might not usually update, such as web.config/app.config or your project file if you have special build steps.

You commit updates of your changes to the server, but in order to receive changes that other users have made and have committed to the server repository you need to explicitly call Update-either on an individual file or a directory.

The Update command gets the latest changes and automatically merges any changes from the server with your code. There’s no update warning or notification unless there’s a conflict. If there is a conflict, you have to resolve the conflict first.

In most scenarios you should first update, and then recompile your project before committing changes to the repository to ensure that merged changes won’t crash the build. In general it’s best to commit frequently with few changes to make sure that the repository is as up to date as possible.

If you need to see differences between your local copy and any version of the file in the repository, you can check the repository against your local copy and compare. There are two options that are useful: Check for Modifications and Diff, both of which let you know that things have changed.

Check for modifications shows you all files that are different between local and remote. In a list view you can click on a file, which then brings up a Diff viewer. The built-in Diff tool shown in Figure 13 shows a side-by-side view of the differences between your local copy and the server copy.

The tool above is the default Diff tool, but you can also specify a custom Diff tool, such as Beyond Compare.

Subversion and Visual Studio

There’s really not much to say about Visual Studio support because Subversion and Tortoise don’t work inside of Visual Studio. This also means that neither Subversion nor Tortoise SVN understand anything about Visual Studio file relationships such as ASPX and ASPX.CS files. Every file is treated as a single entity and so you need to manage any file relationships on your own by checking in and updating all files explicitly.

When you’re dealing with projects and solutions you also want to carefully consider whether project and solution settings affect other users. For example, you may have local settings for connecting to a local copy of SQL Server that has a different server name than for other users. Or your Web virtual path you created locally is different than that in the main application. Or your local paths may not be the same as the projects in the repository.

You may have to check out the project and solution files, modify them, and then leave them checked out permanently on your end to avoid updating your locally specific changes back to the global repository. It’s best to have settings configured in such a way that they work for all developers on the team, but that’s not always possible. Documentation of which parts of .config files need to be managed explicitly can be extremely helpful to get new developers up to speed as quickly as possible.

Visual SVN

If you prefer to have Visual Studio integration for source control, you can check out VisualSVN (http://www.visualsvn.com/), which provides integration with Tortoise SVN directly from within Visual Studio (Figure 14). VisualSVN works with your existing Subversion folders so it doesn’t use Visual Studio version control provider (SCC). Rather, it talks to the Tortoise SVN APIs and gets its data directly from the file store.

VisualSVN provides most of the functionality of Tortoise directly in Visual Studio and you’ll see Tortoise dialogs pop up for most of its operations. What’s nice about the integration with Visual Studio is that it knows about Visual Studio .NET file types and automatically adds files to the project to source control-it saves an extra step so you can use standard Visual Studio project workflow to manipulate project items. One thing that’s definitely easier is creation of new projects-you can just use Add to Subversion and VisualSVN will take care of creating the branch and checking out the files for you.

Although I’ve been using VisualSVN for a while now, I still find myself working in Explorer with the shell integration a lot-it’s often quicker. It’s definitely nice to see the status of files right in the IDE and it’s also nice if you frequently add new files to the system as VisualSVN knows about Visual Studio file associations and automatically adds all related files.

This tool isn’t free-it costs $49 per user, but it’s well worth it if you think you need the Visual Studio integration.

There are several other Visual Studio Subversion add-ins available including the free tool called Ankh, but I had a number of issues with it so I didn’t try it for long. Development on Ankh seems to have ceased a long while ago, so it may be an abandoned product.

Subversive Development

Subversion has been a great boon for me. How can it not be with such a subversive name? I’ve teetered back and forth between using source control and not using it in the past, because I’ve had my share of problems with various Visual Studio source control providers. I’ve used several different tools on projects and in my own work, but most of the problems seem to originate not with the tools but within Visual Studio itself. The end result was that I’d use source control for a while and give up because it got in the way.

Since I started working with Subversion, I’ve had no complaints about problems or compatibility in projects-even when using projects across multiple source control repositories, and that’s as it should be. I now use source control on every project-even if it’s purely local and for myself. Source control should be an unobtrusive tool that helps you be more productive and not get in your way. Subversion fits that bill nicely.

In this article, I’ve only covered the basics of getting up and running. Subversion supports all of the advanced features you’d expect of a top-notch source control system. If you need that functionality, it’s there for you. But if you’re just getting started, stick with the basics until you get familiar with Subversion and how it works-even the basic features take you a long way towards source code security and proper sharing between multiple developers.

There’s much more functionality to cover and, if you want to find out more, you can read through the very comprehensive and even very readable Subversion and Tortoise documentation. Check it out and get Subversive yourself.