Sublime Subversion

Sublime’s powerful Repository Template feature allows you to create templates that users can select when creating new repositories.  These templates can include folder structures and files that should be created for each new repository.  Creating a basic template is as easy as creating the folders and files, and then editing a few lines in a text file.  However, one of the more powerful features of Sublime is to create templates customized to each new repository.  This, can take a bit more work.

A customized template is one where repository details (name, description or owner) are used when the new repository is populated from the template.  Typically this is used to simply rename files or folders to match the name of the new repository.  But what if you wanted to go farther?  In this post I’ll show you how to create a template containing full Visual Studio solution including multiple projects, all of which will be customized to each new repository.

1. Create a new Visual Studio Solution

Start up Visual Studio and create a solution to be used as your template.  You can create multiple projects, default classes, etc.

New Visual Studio project

2. Rename Files and Folders

Next, close Visual Studio and navigate to the folder containing your solution.  Rename your files and folders using the placeholders below so that they will be renamed when your new repository is created.

• %name% – name of the new repository
• %name-formatted% – name of the new repository formatted for a file system (removed spaces and special characters)
• %description% – description of the new repository
• %description-formatted% – description, formatted for a file system
• %owner% – owner of the new repository
• %owner-formatted% – owner, formatted for a file system
• %guid[0]% – %guid[100]% – unique guids which will be generated when the new repository is generated

Be sure to remove any unwanted files and folders such as bin, obj, or .suo and .user files.

Renamed files and folders

3. Modify Solution Files

The next step is a bit tricky.  Open your Solution File (.sln) in a text editor such as Notepad.  Locate the project names and again, use the placeholders above to rename the names and paths.

Modify project names and paths

Next you must replace the solution GUID and project GUIDs with placeholders so that new GUIDs will be generated for each new repository.  Start with the solution GUID used for each project and replace it with %guid[0]% (leave the GUID braces).

Replaced solution GUIDs

Next you must replace the GUIDs for each project.  Assign numbers to each project starting with 1 and keep a note of which project has been assigned what number.  In my case I chose to use alphabetical order.  Now, select the GUID for the first project, and using Find and Replace, replace it with %guid[1]% (again, leaving the braces).  Do the same for each project, each time using a new guid.

Project GUIDs replaced

Save and close the modified solution file.

4. Modify Project Files

Next, open each project file (.csproj, .vbproj, etc) in a text editor such as Notepad.

First, replace the GUID in the <ProjectGuid> tag with the guid that you assigned in the last step (i.e. %guid[1]%).  If you set up project dependencies when you created your solution, you may need to update those as well.

Next, update the <AssemblyName> and <RootNamespace> tags to use the placeholder names for your new repository.

Modified project file

5. Modify Code Files

Next you may need to modify your source code files to replace namespaces with placeholders.  For example, in this example we replaced the namespaces within the Global.asax and Global.asax.cs files.

Renamed Namespace in Global.asax.cs

6. Finalize Repository Template

Next build out the rest of your repository template structure.  Remember that the files and folders you create will populate the entire repository, so you must create the “tags”, “branches” and “trunk” folders as well.

Complete repository template structure

7. Register the new Template on your Sublime Server

Finally, copy the entire template structure to the Templates folder on your Sublime server (typically C:\Program Files\Sublime\Templates).

New Template copied to Templates folder on Sublime server

Then open the “templates.txt” file and add the details for your new repository template.  See the administrator guide for details on modifying the “templates.txt” file.  Be sure to include the “replaceTokens = true” line for this new template.  Otherwise the placeholders you created will not be replaced with actual values.

Add the new template to templates.txt

Save “templates.txt” and perform an IISRESET.

8. Test the Template

Finally, create a new repository using the new template to ensure it is working properly.  It is a good idea to create a repository, check it out, and open the solution in Visual Studio to ensure that the project builds and that all names are being replaced properly.  If you missed any files or namespaces you can simply edit the template on the server and try again.

Create a repository from the new template

Download the Sample

You can download the sample repository template created for this walkthrough from the link below.

Download the sample Template

Even if you are new to Subversion you have likely heard terms like “trunk”, “branching” and “tags” thrown around.  If you are coming from a source control system like CVS you may already be familiar with these terms but if you are coming from a tool like Visual Source safe they may be new.  This post provides an introduction to these concepts in Subversion.  For more in-depth information please see Chapter 4 of the Subversion Book.

First things first – the trunk.  In Subversion, the term trunk refers to your main source code tree.  If you are starting out a new project, you will spend the majority of your time making changes and committing them to the trunk of your repository.  This is because early in a project there are fewer situations where you need branches or tags (there are certainly exceptions depending on your team and development practice, but this is an introductory article and we won’t get into that).

Now, let’s say your project is moving along and getting fairly stable, but you want to experiment with adding a new feature.  You could simply start making changes in your working copy and see how they work out without ever committing them, but this would be a mistake.  If this is a large set of changes your work could span multiple days – even weeks.  At some point your manager is going to wander over to your desk and inform you that there is a critical change that needs to be made RIGHT NOW. Now you’ll need to set aside those experimental changes, get a fresh copy of the trunk, commit those, somehow port those changes into your experimental code, etc etc.  It gets complicated fast.

Branching is specifically designed for situations like this.  A branch is a copy of your source code – typically a copy of the trunk – with a special name like “experimental feature”.  It sets up a space for you to work and make changes without committing to the main trunk.  Once the code in your branch is complete, you can merge your changes back to the trunk.  In addition, as new changes are committed to the main trunk, you can merge those changes into your branch so your branch is up to date with the latest changes from the trunk.  This is a great habit to get into by the way because it makes the process of merging your branch back to the trunk much much easier when the time comes.  Not to mention the fact that you are much more likely to catch potential integration issues early.

I’ll come back to branching in a bit, but now let’s move to tagging.

A tag is simply a named version of your code at a particular point in time.  For example, let’s say you’ve reached version 1.0 of your project.  Rather than having to remember that version 1.0 was revision 638, you can create a tag and give it the name of “1.0″.  Best practice is to create a tag for every major release or milestone (beta, 1.0, 1.1, 2.0, etc) but you can create tags for any point in time you think developers will care about in the future.

So we’ve covered the basic concepts, now I’m going to let you in on a little secret.  Ready?  In Subversion, there is literally nothing special about a branch, or a tag, or the trunk for that matter.  It’s just a directory in your repository which holds a version of your source code.  That’s it.  In most Subversion repositories the directory for storing branches is called, well “branches”, but that is just a naming convention.  You could call yours “superman” and Subversion would still behave exactly the same.

Here’s what I mean.  Most repositories will have the following structure at their root:
/branches
/tags
/trunkEach path above is simply a directory in your repository.  Trunk is self explanatory – it contains your main development tree.  Branches is a folder which will contain sub-folders, one for each branch.  Tags is the same – a folder which will contain sub-folders for each tag.

Here’s what your repository might look like with several tags and branches:

/branches
/branches/new_feature <- branch for implementing a new feature
/branches/1.0_maint <- branch for doing maintenance on version 1.0
/tags
/tags/0.9 <- version 0.9 release
/tags/1.0 <- version 1.0 release
/trunkWhen you create a branch, or a tag, Subversion is simply copying your current code usually from the trunk (although not required) into a new folder in /branches or /tags. Once your code is copied, you can check out a new working copy from that location, make changes, commit, etc. Since your working copy points at the branch folder rather than the trunk, changes you make will only be committed to the branch and not to the trunk. The act of merging is essentially picking the changes you have made and moving them back into the trunk. Subversion gives us tools to make this easier, but it essentially boils down to just that.

Now, why is this important? Well for one it means you aren’t stuck with the standard naming convention of branches, tags, and trunk. If you prefer something like “variations”, “labels”, and “root” it is entirely up to you – Subversion won’t care. However, unless you have a compelling reason to change, it’s best to stick with branches, tags, and trunk because it is widely accepted as the standard naming convention.

Another reason this is important is that Subversion isn’t going to limit you from making mistakes like checking out a tag and making changes to it. Making changes to a tag goes against the entire purpose of a tag because a tag should be a static point in the history of your code – not something you make changes to. If you need to make changes to version 1.0 outside of your trunk (maintenance for example) you should make a new branch using your 1.0 tag as the source (step by step instructions is beyond the scope of this article).

So that’s it. Branches, tags, and trunk are simply standard folders in your repository set up to help you manage your development process. You can change these conventions if you wish, but you should have a solid reason for doing so. You can also add to this structure if you need additional controls for your development team or process.

Before closing I want to make one point about how your code is copied to a branch or a tag. Subversion is smart enough not to make an entire duplicate copy of your code each time you create a branch or tag. It simply creates a pointer to the revision your branch is based on. When you make a commit to the branch, Subversion stores the difference between the modified version and the original file. It does not create a full copy of the file.

Sublime will automatically send email notifications to your developers after a commit is made.  You can enable email notifications for your repositories by navigating to the Repository in Sublime, clicking the Edit Settings link, and changing the Email Notification setting to “On”.

By default, each email notification looks like this:

Default subversion email notification

However, this can be customized by editing an HTML template file located on your Sublime subversion server.

1. Connect to your server using Remote Desktop
2. Locate the “bin” folder inside your Sublime installation directory (C:\Program Files\Sublime\bin by default).
3. Make a backup copy of the file “EmailTemplate.htm”.  This is optional, but recommended so that you will be able to revert to the default template if you wish.
4. Now, using a text editor such as notepad, open “EmailTemplate.htm”.
5. Modify the HTML to customize the body of the email message.  When Sublime sends an email notification, it replaces certain placeholder tokens in the email template with actual commit details.  For example, “{REPOS}” is replaced with the name of the repository.  A complete list of placeholder tokens is listed below.
6. Save “EmailTemplate.htm”.

Here’s an example of a customized email template.  We have added our company logo at the top, and excluded some of the commit details.

Customized email notification

Placeholder Token Reference

The table below contains the complete list of placeholder tokens which may be used in your email notification template. The example for each is taken from the screen shot below the table so you can see exactly where the token is used in the email notification.

Default subversion email notification

This article summarizes a few tips and tricks for working with Subversion from the Visual Studio IDE.  Note that these tips assume that you are using TortoiseSVN as your SVN client.  However, they should hold up whether you are using an SVN client integrated with Visual Studio or simply the command line.

1. Ignore bin and obj folders

One of the first things you should do with any new solution or project is to ignore the bin and obj folders that are automatically created when you compile your project.  Here are the steps I follow when adding a new project to your solution:

1. Add the project in Visual Studio
2. Compile once
3. Close Visual Studio and add the new project folder with TortoiseSVN
4. When adding the project folder, be careful not to also add the “bin” and “obj” folders
5. Commit your changes from TortoiseSVN.  When the commit dialog comes up, right-click on the “bin” and “obj” folders and select “ignore”
6. Finish the commit.

2. Ignore .suo and .user files

These files pop up from time to time and you want to watch out for them.  These files are specific to each user, so if they get committed, everyone will be continuously prompted to resolve conflicts because their version differs from the version in Subversion.

3. Close Visual Studio between commits

I’m going to catch a lot of flack for this one because it seems like a pain.  But it’s really not that hard and it will help you avoid making multiple commits for a single change because .csproj or .sln files hadn’t been saved yet.  For example, let’s say you add a new .cs file to your project.  You code it up and are ready to commit.  Switching over to TortoiseSVN you see your new .cs file needs to be committed, but nothing else.  You commit that file and keep working.  However, the .csproj file has been changed to, but it has only been changed in memory and not saved to disk so TortoiseSVN doesn’t see the change.  You are now left in a position where only the new .cs file has been committed, and the .csproj file hasn’t.  Ideally both files would be committed at the same time because together they represent the addition of your new .cs file.

My workflow is this:

1. Decide what feature or bugfix I’m going to work on
2. Open visual studio.
3. Make the changes necessary for that feature/fix only.
4. Test
5. Close visual studio
6. Commit from the root of my working directory to get all files changed
7. Go to step 1

4) Don’t accidentally deploy .svn folders

This one is easy to overlook especially when it comes to ASP.NET projects.  Subversion creates a hidden .svn folder inside each folder of your working directory.  If your deployment “process” consists of copying your ASP.NET project folder and all sub folders (images, css, etc) and pasting them on your web server, you’re going to be copying all of those .svn folders along with it.

There are really two options to avoid this.  The first is to use the “export” command from Subversion.  If you are comfortable installing the Subversion command line client on your target server, then you can run a command like this to deploy your changes:

C:\> svn export svn://myserver/myrepo/trunk C:\inetpub\wwwroot\mywebsite

Once you have done that you’ll also need to copy over the DLLs because the bin folder won’t be included in the repository (assuming you followed tip #1).

A better solution is to use some sort of continuous integration or automated build process.  Cruise Control.NET is a great solution for this sort of thing.

That’s it for now.  I’ll return to this post and update it from time to time as I identify more tips and workarounds.  Please share your own tips by commenting below.