ource 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 state 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.
You’ll see how to install and configure the Subversion source control tool and a walkthrough of the basic steps required to set up local Visual Studio projects using Tortoise SVN. Note that this article isn’t meant to be a comprehensive tutorial on Subversion; it’s a quick, what-you-need-to-know, step-by-step installation guide.
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 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. Instead, Subversion manages changes by merging source files with any changes made, and notifies you of conflicts only if there are changes that cannot be merged (such as conflicting changes to the same line of code).
Coming from a background of using integrated security in Visual Studio, the merge approach seemed doubtful at first; however, it turns out that it smooths the development process considerably, because 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 integrated source code control provider. 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, where the provider manager often gets confused, especially in complex Visual Studio solutions and shared project scenarios. Using Subversion has simplified many irritating scenarios that formerly required constant fiddling with Visual Studio and the source providers.
Subversion is based on a file system tracking mechanism, so it is essentially tool agnostic. In fact, I now use Subversion with both .NET projects and my old FoxPro projects?the process is identical, which helps with consistency. Subversion also allows storage of all sorts of files, from documentation to support files, that otherwise wouldn’t be part of a Visual Studio project.
|Editor’s Note: This article was first published in the July/August 2008 issue of CoDe Magazine, and is reprinted here by permission.
To start, download Subversion and Tortoise SVN. Install Subversion, and then install Tortoise SVN. If you want Visual Studio integration, check out VisualSVN ($49.00) or the free Ankh tool.
Tortoise works as a front-end UI to Subversion. They are version-dependent, 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. 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.
|Figure 1. Tortoise SVN Settings General Tab: It’s a good idea to set up Tortoise SVN to use _svn instead of .svn, because Visual Studio has issues with directories that start with a period.
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, then choose Settings and check the “Use ‘_svn’ instead of ‘.svn'” check box on the General tab as shown in Figure 1.
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 Tortoise SVN stores all the versioned data. 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 (a separate install). The key is that you need to create the repository on that machine.
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:
- Create the folder d:subversion.
- Right-click TortoiseSVN and choose “Create repository here.”
- Set up permissions for this repository.
To set up permissions, you need to configure d:subversionconfsvnserve.conf and set a password.
[general] # anon-access = read auth-access = write password-db = passwd realm = SummaLp
This configuration enables only authenticated access to the repository, 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). Alternatively, 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. However, the HTTP integration runs through Apache and offers better security and authentication, as well as access through port 80. This article describes only how to use the TCP/IP Daemon service.
The file BIN directory of the Subversion installation provides the service. While you can run the .exe file explicitly to start the server you’ll definitely want to install it as a service instead. 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 filessubversioninsvnserve.exe" --service -rd:subversion" displayname= "Subversion Server" depend= Tcpip start= auto
|Make sure the paths in the preceding command 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 where nn is the port ID. Check for other options in the documentation.
To start the service through the Service Manager or from the command prompt, use the command:
sc start svn
You should only have to do this once; if you installed the service using the command shown above, the service should auto-start the next time you start Windows.
Check the Repository
To make sure the repository works, launch 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://
Open the repository by double-clicking the node. If you get an error message, 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. For 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.
When you can open the repository without errors, you are set up for shared source control with Subversion.
Adding Projects and Files to Source Control
Next, here’s a walkthrough showing how to add Visual Studio projects to Subversion’s 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.
You need to 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 a structure such as:
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.
The examples here 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. Therefore, it’s best to avoid using the Import feature here. Instead, create a directory in the repository without any files, check out the folder, and then manually add files and subfolders.
Here’s the procedure:
- Go into TortoiseSVN and select Repo Browser (right-click, choose Tortoise, and then choose Repo Browser).
- Use the Create Folder option to create a new top-level folder just beneath the main repository (name it SummaLp).
- Go back to Explorer and go to or create a SummaLp folder.
- Right-click the folder and select “Checkout?” as shown in Figure 4.
- Select the top-level folder in the repository and point at the corresponding local path as shown in Figure 5.
|Figure 6. Source Control Icon: Folders and files under source control show up with icon overlays that show checkout status.
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 so Subversion will watch it. Go back to Explorer and check the folder; it should have a green checkmark icon next to it now (see Figure 6).
Don’t just import everything listed below in one pop: It’ll be much easier to create the project folders in the repository first, and then add the individual files after the folder is under source control.
Select one of the project folders and basically follow the same routine as above.
- Go into Tortoise and browse to your repository.
- Create a folder with the project name below the SummaLp folder (SummaLpManager).
- Go into Explorer and check out into the corresponding folder. This puts the project folder under source control.
- Select files and folders, right-click, and then add as shown in Figure 7.
|Figure 7. Adding Files: You can add files to source control and the repository from your local installation using the “Add?” option.
Be selective, and if necessary, add files individually rather than adding entire subfolders. You’ll want to skip over folders such as the obj folder, notes, suo, .user files, log files, and anything else that you don’t want tracked.
After adding the files, you’ll see a directory full of files with plus signs next to them. The plus sign means the files have been added to the local store but not synched with the server.
To sync them with the server, right-click on the project folder, and select “SVN Commit” as shown in Figure 8.
|Figure 8. Committing Changes or Added Files: To commit any changes or added files to the repository, use the SVN Commit option.
|Figure 9. Synched Local Copies: After you’ve added and checked in all files, you should see a clean repository with all green checks.
The commit process basically tries to synch all local changes to the server. In this case, committing copies the new files to the server and into the repository. If there are any conflicts, such as 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.
After committing, your local copy should be up to date, as shown in Figure 9. Your repository is now synched.
The repository now holds the same set of files as your local folder containing the “controlled” files. Figure 10 shows the Repo Browser view. Repeat this process for each of the other project folders.
|Figure 10. Repository Browser View: The Repo Browser lets you see all the files in the repository, which should now match the local “controlled” file view.
You’ll also want to add the Solution file to source control. Just add it (click Add) and then commit it (click 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 that other paths remain properly relative.
The repository is now set up and ready for shared use. Here are the key steps to remember when creating new branches and adding new files in the repository:
- Create a folder in the repository first.
- Check out just the folder to your local folder.
- Add files with Tortoise in Explorer.
- Commit your changes.
Creating a Local Copy from the Repository
The work described in the preceding section needs to happen only 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:
- Pick a directory where you would like to create the local copy.
- Right-click and choose SVN Checkout? as shown in Figure 4.
- 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 would choose SummaLp (the top-level folder) and then choose Checkout to bring down the entire project with the Solution file.
Post Setup Cleanup
Remember that after downloading the project to your local machine, you may still have to configure the 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 script maps, etc.
Also, depending on how well you set up the repository, you may be missing some project dependencies. You want 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 trickier. In that case, users must ensure they have the appropriate components registered on their machines. 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.
|Figure 11. Changed Files: Files you’ve changed show with a red warning icon meaning they need to be committed.
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.
|Figure 12. Viewing Changes: SVN Update lets you see and choose files that have been changed in the repository.
You commit updates of your changes to the server, but 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 on a directory (see Figure 12).
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, but if a conflict occurs, you must resolve the conflict before the Update will complete.
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 run a comparison. There are two useful options: “Check for Modifications” and “Diff,” both of which let you know that things have changed.
The “Check for Modifications” option shows you all files that differ between the local and remote versions. 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.
|Figure 13. Side-by-Side Changes: The built-in Diff tool lets you quickly see changes between your local copy and any version in the repository, and lets you update your copy.
|The tool shown in Figure 13 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 that between .aspx and aspx.cs files). Every file is treated as a single entity, 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 the 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. Documenting which parts of .config files need to be managed explicitly can be extremely helpful in getting new developers up to speed as quickly as possible.
|Figure 14. VS Integration: VisualSVN integrates Tortoise SVN directly into Visual Studio.
If you prefer to have Visual Studio integration for source control, you can check out VisualSVN, which provides integration with Tortoise SVN directly from within Visual Studio (see Figure 14). VisualSVN works with your existing Subversion folders, so it doesn’t use the Visual Studio version control provider (SCC). Instead, it talks to the Tortoise SVN APIs and gets its data directly from the file store.
VisualSVN gives you access to most of Tortoise’s functionality directly from Visual Studio, and you’ll see Tortoise dialogs pop up for most of its operations. What’s nice about the integration is that VisualSVN knows about Visual Studio .NET file types, and automatically adds project files to source control. That saves an extra step, and lets you use standard Visual Studio project workflow to manipulate project items. One thing that’s definitely easier is creation of new projects; you just select Add to Subversion and VisualSVN takes 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 frequently?it’s often faster. It’s definitely nice to see file status right in the IDE, and it’s also convenient if you frequently add new files to the system, because VisualSVN also understands Visual Studio file associations, and automatically adds all related files.
VisualSVN isn’t free?it costs $49.00 per user?but it’s well worth the price if you need the Visual Studio integration.
There are several other Visual Studio Subversion add-ins available, including a 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.
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 then give up, because it got in the way.
However, 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, not get in your way. Subversion fits that bill nicely.
In this article, I’ve covered only the basics to get up and running. Subversion supports all 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. To find out more, read through the comprehensive and very readable Subversion and Tortoise documentation. Check it out?and get subversive yourself.