# Thursday, 24 May 2012

At my current job and my last I either worked solo often on projects or in very small overlapping efforts of a few team members.  In both of these jobs the team used Visual SourceSafe (VSS) and it was working well enough but no longer supported. Jumping to TFS felt like overkill for a team on VSS and not affordable. 

MS has announced TFS Express which might go a long way in changing this. However, I have found the world of Distributed Version Control Systems (DVCS) with Git and Mercurial to be game changers.

As I have been learning more and more about DVCS I found a need to work up a new process that I can hand over to my team members or a new employee to help them get up to speed fast. Teams of larger size or even code bases of much larger complexity require sophisticated workflows. In my last two jobs I haven’t fallen into this category. 

This series reviews the process I have put together for a small team (1-5 members) with less complex code bases.  I’m not a Mercurial or Git expert by any stretch of the mind but I have found a flow that is working great. I welcome any thoughts and suggestions for improvement from the more seasoned DVCS pro’s.

Let’s get started.

1. Mercurial or Git?

2. Installing and basic configuration of Mercurial

3. Workflow basics

4. Setting up your repository

5. Working in default

6. Reverting/Deleting

7. Branching

8. Tagging & further reading

Posted 05.24.2012  #    Comments [0]  | 

This is the fourth stop in this series.

I’m first going to mention using the command line and Nuget Package Restore.

To command line or not.  That is the question...

First time users, especially Windows heavy users such as myself have likely used Tortoise* at some point in our development to interact with a repository.  I started with TortoiseHg to help get the basics down but after Rob's challenge I gave the command line a shot and discovered two things.

  1. I was faster
  2. I understood Mercurial much better and what Tortoise was doing for me.

I still use Tortoise for a few things but for the most part I use the command line now for most operations. If you think this is the way for you have a look at posh-hg to add even more productivity.

Nuget Package Restore

Feel free to move on to the next section if your not using .Net.

Dependencies are something we must deal with in our version control story.  Nuget eases a developer’s life for managing dependencies but with Nuget Package Restore we can more cleanly keep our dependencies out of the source control but have an automated way of getting them into your project. 

Without Package Restore we would have to put the dependent libraries (dll's) in source control.  Usually one would create a library folder and have everything in this folder source controlled. 

With Package Restore we source control the configuration settings of the dependent libraries we are using with Nuget.  When we pull down a repository for the first time and build it Nuget will read the configuration and download all of the libraries in use.  We get a source control environment with the knowledge of what libraries we need but we don’t have to store the libraries in the source tree. 

To use it we’ll need to tell Mercurial to ignore the packages folder. The last item in the hgignore file in the third post has this covered. 

If you don’t like this idea, no problem.  You don’t have to use it.

Setting up a repository on your local machine

I do this with Tortoise although you can use the hg init command at the command line.

To use Nuget Package restore follow the instructions from David Ebbo’s post.

With TortoiseHg installed right-click on the root project folder.

Select TortoiseHg, Create Repository Here.


Keep the defaults and press Create.


Overwrite the hgignore file.

Either copy an hgignore file from another existing project in another folder OR copy over the text in the hgignore file with the text in the Ingore file section above.

Commit your project's initial state.

I do this with TortoiseHg as well.

Right-Click your root folder and Select HG Commit.


1. Check of the Check box in the upper left hand corner.  This tells Mercurial to add everything in the list.

2. Add a commit message.

3. Press Commit.


When prompted to add select add


Adding Nuget.exe (http://blog.davidebbo.com/2011/08/easy-way-to-set-up-nuget-to-restore.html)

Since we are using Nuget Package Restore we have to add the Nuget.exe to the repository.  Normally we don't want to save Dll's and/or Exe's to the repository.  The ignore file specifies this as the default.  As such we have to add it manually.  The same is true if down the line you need to use a 3rd party library that isn't available on NuGet.  In this case I would create a lib folder in the root of the project and place my library files in this folder.  From this folder I would add it to the repository and add a reference in VS.

Go to the .nuget folder in the root of your project directory.

Right-click nuget.exe, select TortoiseHg, Add Files... 

Keep the defaults and press Add


Notice the Icon changed to a plus sign for the file.

Select the Nuget.Exe file again and select Hg Commit


Add a comment and commit.


Your project is ready to go.

The next in the series will go into the commands for working in default.

Posted 05.24.2012  #    Comments [0]  | 

This is the third installment in Getting started with Mercurial for a small team

In this post we’re going to cover Workflow basics.

Mercurial / Team Workflow Practice

In a small team often the workflow process is not something that has to be complex.  There are a few different workflow techniques that make sense in this case.  Even in a 1 person team branching and tagging may seem unnecessary butthey can come in handy. 

First, here are a few great articles on workflow practices.



Steve Losh’s guides are priceless and serve as the basis for the workflow process described below.

Branch as needed (Read Steve’s description and come on back.)

The name may seem a little deceiving but essentially the recommended approach is to not worry about branches in general.  Development on the main line / default branch should work a lot of the time for a small team. Often when you are working in small team’s you don’t have to worry about features others are working on since you are likely the only one.  In the small cases as well where a few are working it is often in a way that they can develop features that are completely part of a different area of the code than you are working on.  You often don’t have to worry about updating the code base for a "hotfix" either which if you were developing off the default branch could present a problem should this be needed.

The reality is even in a small team you will want to think about these possibilities and plan for them if they will be an issue.  Hence, "Branch as needed".  If you don’t need it, then don’t worry about it.

When you do need to branch there are several techniques described at http://stevelosh.com/blog/2009/08/a-guide-to-branching-in-mercurial/.

Branch with Named Branches

Even for small teams or code bases, branches offer some great advantages and should be considered a part of your process.  Branches offer a way for you to create a separate isolated area for you to develop a feature or bug fix.  This isolation allows us to fully develop the feature or bug fix without touching the default line. 

This gives us the flexibility to get rid of the branch if we decide it’s not working or work a fix in on the default line while we are still developing the feature on it’s own.  If we were not using a branch and a serious bug is found the feature code may stop you from being able to issue a fix for it until you’ve completed the feature.

I tend to use branches for features that I deem larger than a week to work on or if I am really unsure of how I want to accomplish it that way I can get rid of my work easily if I decide to scrap it and start over.

There are several ways to create branches in Mercurial.  Were going to use the Branching with Named Branches process. Branching with clones is also a great option if you are really unsure of your work and think you might need to trash it.  This is the simplest for trashing but requires a bit more work if you like it and want to merge it back into the original codebase.

Another very good approach is to use a stable branch for releases and have default be where you mainly develop. http://stevelosh.com/blog/2010/05/mercurial-workflows-stable-default/.  Depending on your need for your product line this option may be a great option as well.

Next up, setting up your repository.

Posted 05.24.2012  #    Comments [2]  | 

This is the second post in the Getting Started with Mercurial for a small team.

This post is going to cover Installing and basic configuration to get started using Mercurial on Windows.

Installing Mercurial on Windows

I've installed Mercurial two ways and have found both very easy to use.

With TortoiseHg (all in one download)
Using Chocolatey (package manager for your applications on the PC, think NuGet for your PC apps!)

Mercurial Settings

There's several settings you can set per repo and/or globally on the machine.  The first of these to set is your username.

To set this at the computer level on a windows machine, find the mercurial.ini file in the Windows System UserProfile folder.

Add the following:

username = Your Name <your_email_address>

You can also set it per the project by editing the hrgc file in the .hg directory for your repository.

Ignore File

The ignore file (.hgignore) tells Mercurial what files to not source control by default.  You can add anything manually in the list yourself but Mercurial won't automatically look for the patterns in this file.  There are several examples out there.  Below is the sample I am using at the moment and have found it to work well.

# Ignore file for Visual Studio 2010
# use glob syntax
syntax: glob
# Ignore Visual Studio 2010 files
packages #be sure to manually add nuget.exe in the .nuget folder

The two resharper entries aren’t needed if you don’t have Resharper. The last entry we’ll explain in a later section.
Mercurial Basics

There are a lot of great resources on the internet for this.  Here's a recommended list that I found invaluable in getting me started.


http://hgbook.red-bean.com/read/a-tour-of-mercurial-the-basics.html (the whole book is good)


http://tekpub.com/view/dotnet-oss/7 (Free video on Mercurial with CodePlex)

Command cheatsheets




Bitbucket Basics

Bitbucket also has a nice tutorial of their product at http://confluence.atlassian.com/display/BITBUCKET/bitbucket+101.

Play around, run through the samples in the resources above.  Getting the absolute basics down will help you for the next in the series, Workflow Basics.

Happy Coding! Smile

Posted 05.24.2012  #    Comments [0]  | 

This is the first in the series Getting started with Mercurial for a small team.

Distributed Version Control Systems (DVCS)

DVCS offer many advantages over traditional systems such as Subversion.  Most agree that branching and merging are much easier, the operations are usually much faster and the reason I like the most – their distributed.


Every developer has a copy of the repository on their drive and can work on this copy however they like. This results in much faster operations as well as a new freedom for a developer to work on code locally WITH source control operations and not having to worry about what it is doing to the server version or other users.  Commit 50 times, add two branches, delete a branch, etc.... No more having to worry about checking in to the central server.  Work how you need to complete the task with local source control support!  When your ready you can get an update for the "central" server and check your work/build locally.  Then commit and since merging is so much more powerful and intelligent this isn't as scary as before.  A developer can get your changes from the central repository OR EVEN YOUR repo (if setup) when they want to their repository.

Trust me, I'm not giving it enough justice.  DCVS is here to stay and is the only way moving forward.  Now it comes down to currently two really great choices. 

Mercurial vs. Git

Both are great,  so why Mercurial?  My decision came down to three reasons.

  1. Mercurial has better tooling on Windows.  I am sure Git will change this but today this is the case.
    • As of this week, Git released a Windows client.  This may change the game but I haven’t had a look at it yet.
  2. Mercurial is a little simpler to use. Think of Mercurial as less options but not hobbled and Git as the option full, can easily shoot yourself if you don't know what you are doing option. 

They both are great!!!! In fact I recommend a developer learn both. #3 is listed below.

Bitbucket vs. Github vs. Self-Hosting

The final reason for Mercurial is not based on Mercurial.  The cloud hosting service Bitbucket offers a free plan that includes unlimited private repositories for up to five users.  Github offers free to open source. 

Bitbucket offers both Mercurial and Git hosting so choosing which DVCS is a little easier as it can be changed fairly easily. Bitbucket offers repo conversion tools as well.

Self-Hosting? - Yes, it's possible but setting up a Mercurial server at this time seemed more work and maintenance than it's worth compared to cloud hosting.

Here’s a few more examples of others who use Mercurial.


http://www.headspring.com/2012/03/migrating-from-bitbucket-to-github (Using both)

The team making stack exchange (stack overflow sites) also use Mercurial and have created a terrific tutorial.

Security with the Cloud

Worried about your source? Bitbucket is secured by HTTPS and requires a login with access to the repositories and / or SSH Keys per machine accessing the repository. A repository is owned by an account and that account can grant access to other accounts. Ownership of a repository can be transferred to another but only by contacting Bitbucket support.

While this is secure, dillegence in coding & backup practices should still be followed such as avoiding storing passwords where possible and backing up our source.

Secure Code

Storing the connection string in the clear in the web.config is a risk that can be mitigated. You can encrypt your connection string information and other sections that might contain sensitive information. You could have a connection string configuration file on each machine/server you use at a specified location and just have your web.config point to it to keep it completely out of source control. 


Relying solely on any cloud vendor as your source code backup strategy is a nightmare waiting to happen. The cloud never goes down or looses data. Don't kid yourself. Don't play the fool and leave it all up to the cloud. 

Going down for a little while using a DVCS is not that big of a deal.  You can keep working and there are ways to get work from another peer box (hg serve).

DVCS being distributed by nature can make small outages very tenable. When you pull down a repo from the "central" repo, which in DVCS can change but for our purposes will always be considered Bitbucket, you are getting the entire repo UNLESS you purposefully choose different.  This means your local repo is a copy/backup.  That does not mean you should entirely rely on this in a disaster BUT it is an extra layer. 

I recommend backing up the Bitbucket repositories on a regular interval and store them elsewhere.

Currently, there are two ways to do this. 

  1. Log into bitbucket and download the source for each repo in a zip file.  This has one major drawback.  The zipped version will not include any version control history. 
  2. Use https://bitbucket.org/christianspecht/bitbucket-backup script. This script will download all repo's with version information.  The script is actually cloning all repo's to a destination directory.  The script requires Mercurial to be installed on the machine running it and login information.

The next in the series is Installing and basic configuration of Mercurial.

Posted 05.24.2012  #    Comments [2]  |