Sublime Subversion

Let me paint you a picture.  It’s 5 minutes till 5 at the end of a long work week and you’ve just wrapped up a new feature on your current project.  It’s time to commit those changes and head out for the weekend.  You pull up TortoiseSVN, write a helpful and descriptive commit message (feeling vastly superior to your less-than-thorough colleagues with their randomly generated commit messages), and hit the Commit button.

AAAAAAAARRRRRRGGGGHHH!!!!

AHHHH!  The last thing you want to do is spend the next hour picking through other people’s changes to make sure your code still works.

Now here’s a little secret about developing software with a team.  Merging is just a fact of life.  Unless you want to go back to the old lock/modify/unlock model you’re going to have to merge your changes with someone else’s at some point.  But with today’s software, most merges can be handled automatically by our development tools.  The only real problem arises when you have to merge lots of changes all at once across many different parts of your code-base.  Resolving conflicts (deciding what code to keep when two changes contradict each other) requires intimate knowledge of your code and your colleague’s code.  Not the activity for 5PM on a Friday!

There are two keys to keeping merges simple:

1. Commit frequently with simple, focused changes
2. Update your working copy after each of your colleagues commits changes which may impact you

Commit Frequently with Simple, Focused Changes

As you are making changes to your code, keep a mental note when you shift from one focus to another.  Are you fixing a bug?  Developing a new feature?  Optimizing a query?  As soon as you shift from one focus to another – assuming you are finished with the first thing – commit those changes along with a short, simple description of your changes.  This is good practice in general, but it also greatly reduces confusion when a team member has to merge their changes with yours.  A small, focused change is much easier for someone who isn’t familiar with your code to comprehend.  So if I have to merge my changes with yours, and I see that your change fixes a certain bug, I can be sure to pay attention to that detail when merging so as not to re-introduce the bug into the code-base.

Update your Working Copy Frequently

Staying up to date with the activities of your team is a critical step in reducing and even eliminating the pain associated with merging.  If you see that a colleague committed a change to a file you are working on, you can update your working copy right then and there.  This offers two significant advantages: (1) you will be dealing with smaller conflicts that are usually much simpler and (2) the other developer is probably still in the office if you have any questions.

This is where Sublime enters the picture.  Sublime allows you to stay up to date with your development team using email notifications and RSS feeds.  If you enable email notifications on your project repositories you will be notified immediately when another users commits changes.  If you don’t like email, you can use the personalized activity stream RSS feed which notifies you whenever a user commits changes to any of your repositories.  Both of these methods allow you to quickly scan the commit details including the commit message, and changed files so you can determine if their changes might conflict with your work.

Viewing the Commit RSS feed in Outlook

The amazing thing about these two practices is that (a) they are actually pretty simple to implement and (b) the time and mental energy required for merging changes practically vanishes.  And it’s not just that you are spreading that hour merging commits across the day so it doesn’t seem like it takes as much time, it really does take less time.  The reason for this is that you are eliminating the mental ramp-up time required when you save this for the end of the day or worse, the end of the week.

A good way to think about this is efficiency in testing and fixing bugs.  Fixing bugs while your team is actively engaged in development is vastly more efficient than fixing bugs after your team has disbanded and moved on to something else.  While development is in progress, everyone is already engaged and can rapidly jump to the source of a problem, get it fixed, and move on.  Your brain operates the same way.  While you are working on a particular piece of code, your brain keeps a mental model of that code so that you can quickly navigate from one area to another implementing features.  If you have to merge changes and you already have that mental model, you know exactly how those changes will impact your code and what needs to be done to resolve any impacts.

These two practices really aren’t that hard to implement with your team.  Sublime has features that are designed specifically for making this easy, but even if you are using a different product you can still work to implement these practices.  Once you have worked this way for a few days I guarantee you’ll never want to go back.

We just pushed the final bits live and you can download Sublime 1.2 now!  Version 1.2 can be installed right over top of your existing Sublime 1.1 installation so upgrading is a snap!

We are super excited about Sublime 1.2 and feel that it’s the best version of Sublime yet.  Version 1.2 introduces a slew of new features and enhancements.  Check out the release notes for the complete list of new features and bug fixes included.  Below are the highlights:

• Path-based permissions. It is now possible to manage path-based permissions within your repositories.
• Personalized Dashboard. Each user gets their own personalized dashboard showing them their active repositories and activity stream.
• Activity Stream RSS Feed. Keep track of all of your repositories from a single, dynamic RSS feed.
• Active Directory Groups when using LDAP Authentication. Use existing Active Directory groups when managing repository permissions.
• Advanced Repository Templates. Repository templates can contain files and content which will be personalized to the details of your new repository.  Included are two new templates for Visual Studio projects.  Each template will pre-populate the new repository with a Visual Studio solution file based on the name of the repository.

As you may know, last week saw the Subversion Vision Conference in New York City. This wasn’t a large event, rather it was a small meeting of several core members of the Subversion team. Their goal wasn’t marketing, community building, or flag waving, but rather to step back a moment and take a look at where Subversion was headed. And although they didn’t come away with a finalized roadmap or vision statement, it does appear that some good progress was made on mapping out the direction for Subversion.

I think this is great and I’m glad to see the Subversion team taking some time to map out the future. But I do wish we had seen some indication that Subversion may evolve to incorporate some distributed functionality. However, according to Michael Pilato the immediate plan appears to be to “Maintain a centralized approach to version control”.

Considering the composition of the team – most members being from companies such as Collabnet or WANdisco who serve the enterprise – this isn’t exactly surprising. Centralization is still a key concern for enterprise IT organizations who need to maintain tight control on their systems for compliance and governance reasons. But I hate to see the team dismiss different approaches to source control simply because it doesn’t appeal to the enterprise yet.

I think distributed version control systems have some great advantages and not just in the open source space. I think cheap, personal branching and merging is an extremely powerful tool. From personal experience I can tell you that it can completely change your development workflow for the better. My opinion is that anything that stops a developer from committing changes is a bad thing. Your version control system is your safety net – it should be there to support you, not to impose speed bumps.

I’ve watched the rise in popularity of DVCSs over the last few years. Git made the DVCS sexy but they’ve been around for quite a while. Microsoft supporting Mercurial on Codeplex is just one example of DVCSs being taken seriously by very large players.

But even though distributed systems are the hot “new” thing, most organizations – big or small – still place a high value on centralization. As a small business using Subversion, I see the value in having one location with all of our valuable IP. I have one asset to back up, one place to go to find repositories, one place to go to manage access, etc. These are all great arguments for a centralized system but I think there can be a middle ground.

The combination of a centralized version control system supporting distributed working copies could be extremely powerful. Allowing your developers to commit, branch, merge, and revert locally and then pushing changes up to the master repository as appropriate seems like the best of both worlds.

This is where the Git users out there yell at me and tell me that Github already works this way. I’m aware of that and have used it myself. It’s a great workflow – but it’s not ready for the enterprise, or even smaller companies. It will work for some, but not for the majority.

This is where I think the Subversion team can make some serious traction – not just supporting the status quo – but really moving the product forward in a new and exciting way. I think that Subversion is in the unique position of being able to take advantage of the benefits that distributed systems offer while at the same time serving those who care about centralization.

In the coming months I expect that the Subversion team will make their roadmap public and I’m excited to see what’s on it. I really like what I’ve been hearing about the Working Copy changes (no more .svn folders littering my working copy!) and love to see the momentum in the community. Subversion is still hands-down the best source control solution for small, medium and enterprise organizations, but it can always be better. I hope that the core team will consider some of these opportunities when mapping out Subversion’s future.

Over the last couple of days we have started posting some short tutorial videos. Initially these videos focus on how to use Sublime but over time we will expand the scope to cover Subversion topics as well.

• Tutorial 1: Creating Subversion Repositories in Sublime
• Tutorial 2: Checking out a Repository

Please let us know if these videos are helpful and if you have any suggestions on features to cover or ways we can improve them.

Over the coming months we will be releasing the roadmap for Sublime. This will include new features and updates for version 1.0 (which are available free to all current 1.0 users) as well as future plans. To make sure we are planning the right features for Sublime we have set up a user forum to capture your feedback and ideas. Here you can vote on ideas submitted by other users, or submit your own suggestions.

Currently the top contenders are:

• SharePoint integration – creating a repository will create or connect to a SharePoint project site
• Repository History RSS feed – expose an RSS feed on repository commits – may be used as an alternative to email announcements
• Path-based permissions – allow permissions to be set on paths within a repository
• Active Directory Groups – allow AD security groups to be used when assigning permissions

There are plenty of other ideas as well ranging from an enhanced repository browser, incremental backups, and security/permission audit.

Please help us make Sublime the best Subversion server available by providing your input and ideas!

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

Sublime automatically backs up all of your Subversion repositories on a schedule you define.  In this short article we will walk through the process of configuring your backups, monitoring your server to ensure backups are happening, and restoring a repository.

1. Configuring Backups

To configure your backups, navigate to the Administration section in Sublime and click the “Backups” tab.  First, enter a path for your repositories to be backed up to.  When you install Sublime, it will default this path to be a Backup folder within your Sublime installation directory.  However, it is strongly recommended that you back your repositories up to a network device such as a NAS or remote network share.

Next, enter a time of day and the days of the week that your backups should occur.  Generally this should be a time of the day that users are not using Subversion.  However, Sublime uses the subversion “hotcopy” command when making backups so even if your users are still accessing Subversion you are not at risk of corrupting data or interrupting the backups.

Lastly, enter a backup account to be used when performing the backups.  This account must have read/write access to the Backup path.  It will also be added to the local administrators group on your subversion server.

Scheduling subversion backups in Sublime

2. Monitoring Backups

Each time Sublime backs up your Subversion repositories, it will write an entry to the Windows Event Log.  You can monitor this directly from the Sublime web interface, or by connecting to the server using remote desktop.  Each entry in the windows event log will list the number of repositories backed up, the number of errors (if any), and the duration for the backup.

Successful Subversion backup in the Windows Event Log

If you are using Windows Server 2008, you can create a Custom View to show only Subversion backup messages.  Simply create a new Custom View to display “Information” events filtered where the Source is “Sublime.SubMaint”.

3. Restoring a Subversion Repository

Restoring a repository is essentially copying the backup repository from the backup location back to your Subversion server.  However, as a best practice we recommend the following steps:

1. Take your Subversion service offline.  This ensures that while the restore is underway, your developers cannot commit to the repository.  If you are running Sublime in SVNSERVE mode you can take the Subversion service offline from the administration home page.  If you are using Apache you will have to stop the service manually in the Services console in Windows.
2. Locate the folder containing the repository you want to restore on both your Subversion server, and in the backup location.  The backup location should be a mirror of your repositories folder on your Subversion server, so locating the correct repository should be easy (see below for tips on identifying a repository folder).
3. On your subversion server, delete or rename the folder containing the repository you want to restore.  Then, copy the repository folder from the backup location over to your subversion server.

Let’s look at an example.  In the screen shot below, the left folder is the Repositories folder on our Subversion server.  This contains all of our current “live” repositories.  The folder on the right is our backup location.  If we wanted to restore the “CommonLibs” repository, first we would delete “CommonLibs” from the “Archive” folder on the left.  Then we would copy the “CommonLibs” folder from the backup location on the right and paste it in the “Archive” folder on the left.  The result would be a fully restored version of the “CommonLibs” repository from the time the last backup ran.

The Backup location is a mirror of your Repository location

Once you have restored your repository you can bring the Subversion service back online.  It is also a good idea to reset IIS (open a command prompt and type “iisreset”) to ensure that the Sublime cache is cleared.

TIP: How to locate a repository folder

If you are new to Subversion it may not be clear exactly what constitutes a repository.  In short, a repository consists of a folder containing a number of specific sub-folders and files.  So when we say “repository” we are talking about the parent folder and all child folders and files.

You can identify the repository parent folder by looking at its children.  A repository will contain the following child folders: conf, db, hooks, locks.  It will also contain a file called “format” and there may or may not be a README.txt.  In the following screen shot, we are looking at the content of “CommonLib”  You can see that it contains these folders, thus “CommonLib” is a repository.  The parent folder “Archive” is not – it’s merely a folder.

Identifying a repository folder

Repository Templates are a great way to reduce the time required for setting up a new project, and encourage consistency across projects.  Consistency is important especially in an organization with many different repositories spread over different projects and development teams.  Having a consistent repository structure drastically reduces common errors made by new developers or even experienced developers in an unfamiliar repository.

Setting up Repository Templates in Sublime is as easy as creating a folder structure on your Sublime server containing the files and folders you want to include in your new project.  In this walk-through we’re going to create a Repository Template for new projects using Sharp Architecture.  Sharp Architecture is a perfect candidate for a Repository Template because there are quite a few dependencies that can take a while to download and organize.

In the following steps we’ll be creating a Repository Template for Sharp Architecture, but the same steps can be applied to any number of project types you may have.

1. Create the new Repository Template Folder

The first step is to create the new Repository Template folder on your Sublime/Subversion server.

1. Connect to your server using Remote Desktop
2. Navigate to the “Templates” folder beneath your Sublime install location (typically C:\Program Files\Sublime\Templates)
3. Create a new folder inside Templates called “SharpArch” (note: the folder name can be different from what your users see when choosing a template)
   

   Create a new folder for the template

4. Open the new folder and create the standard Subversion trunk, branches, and tags folders.
   

   Create the branches, tags, and trunk folder

5. Open the “trunk” folder you just created.  Now it’s time to start creating the folder structure for your new project.  For starters, Sharp Architecture projects tend to have a defined top-level folder structures for the different elements of a project: app, build, db, tests, etc.  So let’s create those folders now.
   

   Create the project folder structure

6. Next, if you like you can create README.txt files in each folder explaining what should be placed there.  This is optional of course but can be useful for new developers who may not be familiar with the project structure.

2. Download Sharp Architecture binaries

Now that our basic structure has been created, it’s time to download the related Sharp Architecture binaries as well as their dependencies.

1. Open a web browser and navigate to the Sharp Architecture download page.
2. Download and extract the latest revision (or which ever revision you prefer) of the compiled binaries
3. In the extracted folder, locate all of the DLLs and associated files (located within the “bin” folder as of this writing) and copy them all to the “lib” folder we created back in step 5 of the previous section.
   

   Copy Sharp Architecture binaries to template

3. Register the Template with Sublime

The last step is to register the newly created Repository Template with Sublime.

1. Navigate back to the Templates folder and open “templates.txt” in Notepad
2. This file follows a simple INI file format and you should have two templates already listed (Standard and Empty).  Create a new section with the following structure:
   [SharpArch]
name = Sharp Architecture
description = Use for Sharp Architecture based projects.
   

   Insert new template description into templates.txt

3. In the example above, the section header “[SharpArch]” must be the same as the folder name for the template.  But the value for the “name” attribute is what will be displayed to your users.  There is also an optional “default = true” attribute you can add if you want this template to be automatically selected as the default choice when creating new repositories.
4. Save templates.txt and close Notepad.
5. Next you must restart IIS by opening a command prompt and typing
   C:\> iisreset

4. Test the Template

Open a web browser and navigate to Sublime.  Click on the Create New Repository tab and in the Template section, you should see the new “Sharp Architecture” template.

Preview the new template

Wrap-up

In this walkthrough we’ve created a new Repository template for projects using the Sharp Architecture framework.  We created a folder structure and pre-downloaded all binaries and their dependencies so that new repositories would automatically have this structure and these resources.  This same approach could be taken for any number of project types relevant to your organization.

Using these same techniques you could make your template more robust including common resources such as:

• NANT build script templates
• Visual Studio .sln or .csproj files (although your users would most likely have to re-name them for your project)
• Common scripts or tools used by your organization
• Default config files with references to your development or production environment
• etc

For additional information and complete documentation on creating Repository Templates, please see the Sublime documentation.

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.

The Subversion team announced the release of Subversion 1.6.5 today. This is mostly a bugfix release based on the release notes.

Here are the changes between 1.6.5 and 1.6.4.

User-visible changes:

• fix mod_dav_svn directory view links to preserve peg revisions (r38201)
• do not error on Windows when ALLUSERPROFILE dir nonexistent (r38053, -5, -7)
• properly escape lock comments over ra_neon (r38101, -2)
• allow syncing copies of ‘/’ over ra_neon and ra_serf (issue #3438)
• make ‘svnlook diff’ show empty added or deleted files (r38458)
• fix building with Apache 2.4 (r36720)
• fix possible data loss on ext4 and GPFS filesystems (issue #3442)
• resolve symlinks when checking for ~/.subversion (r36023)
• don’t let svn+ssh SIGKILL ssh processes (issue #2580)
• allow PLAIN and LOGIN mechanisms with SASL in svnserve (r38205)
• fix peg revision parsing in filenames like ‘dir/@file.txt’ (issue #3416)
• fix detection of Apache <2.0.56 (r38290, -3, -4)
• don’t pretend to do tree conflict resolution (r38799, -801, -805)
• fix data corruption when syncing from svnserve to mod_dav_svn (r38686, -7)
• fix GNOME Keyring with ‘–non-interactive’ option (r38222, -3, -61, -410)
• fixed: false “File ‘…’ already exists” error during commit (issue #3119)

Developer-visible changes:

• avoid referencing uninitialized variables (r38388)
• plug a couple of error leaks (r38572)
• improve windows test output (r38616, -7, -9, -49)