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

Many organizations use SharePoint for team and project collaboration.  SharePoint is an ideal location to store project documents, issues lists, and other project artifacts.  However, without a view into the actual development progress for your project you won’t have a complete picture.  With Sublime 1.2 it is very easy to view your repository commit history directly within your SharePoint team sites or even your My Site.

Viewing Project Progress in a SharePoint Team Site

Having a SharePoint site per project is a very common model for organizations who rely on SharePoint for collaboration.  With Sublime’s RSS feeds it is possible to display the commit history for a single repository right within your SharePoint project sites.

1. First, navigate to your project site.
2. Next, under the “Site Actions” menu, choose “Edit Page”
3. Once the page is in edit mode, choose a web part zone and click “Add Web Part”
4. In the Add Web Parts dialog, choose the “RSS Viewer” web part and click “Add”
5. Once the web part is added, click the “Open the tool pane” link to edit the web part properties
6. Next, open a new browser window and navigate to Sublime
7. Click on the Browse Repositories tab, locate the repository for your project, and click the repository to view repository details.
8. In the “History” section at the bottom of the repository details page, locate the orange RSS feed icon.  Right-click on this icon and choose “Copy Shortcut”.
9. Switch back to your My Site and in the RSS Feed URL textbox for the RSS Feed web part, paste the shortcut you copied in step 7.*
10. Click “OK” to save your settings.  You should now see the activity feed for your repository on the project team site.
    

    Subversion history on a SharePoint project site

View your Activity Stream in your My Site

One of the best features in Sublime 1.2 is the personalized activity stream.  This activity stream shows you all activity on any repository you are a member of so you can easily stay up to date with all your projects.  And because this view is personalized it is an ideal candidate for your SharePoint My Site.

1. First, navigate to your My Site.
2. Next, under the “Site Actions” menu, choose “Edit Page”
3. Once the page is in edit mode, choose a web part zone and click “Add Web Part”
4. In the Add Web Parts dialog, choose the “RSS Viewer” web part and click “Add”
5. Once the web part is added, click the “Open the tool pane” link to edit the web part properties
6. Next, open a new browser window and navigate to the Sublime home page
7. On the right-hand side, next to the activity stream there should be an orange RSS feed icon.  Right-click on this icon and choose “Copy Shortcut”
8. Switch back to your My Site and in the RSS Feed URL textbox for the RSS Feed web part, paste the shortcut you copied in step 7.*
9. Click Okay to save your settings.  You should now see your activity stream on your My Site home page.
   

* RSS Feed Permissions

Depending on how you have configured your Sublime security settings, you may need to modify the RSS Feed URLs slightly.

• If you have turned off RSS Authentication in Sublime (available from the Administrative Security page) then you don’t need to make any changes.
• If you require RSS Authentication then you must specify a username and password in the query string for the RSS feed.  The username and password are added to the end of the feed URL as follows:

http://myserver/Feed.aspx?f=repo&r=/path&username=myusername&password=myurlencodedpassword

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.