Getting started with Mercurial for Visual Studio and TFS Developers

I recently had to work on a project that required the use of Mercurial as its source control repository.  Since I am a long time user of Visual SourceSafe, Subversion and Team Foundation Server, using Mercurial was quite a radical change for me and required a bit of a learning curve.

Therefore, I decided that I would share my experiences with others who need to learn and work with Mercurial as well.  In addition, while this article specifically addresses the use of Mercurial, the same techniques can also be used and applied towards the use of Git (another Distributed Version Control System--DVCS).

First of all, to get started with Mercurial, you will need to install the necessary tools to work with Mercurial and Visual Studio:

• TortoiseHg--http://tortoisehg.bitbucket.org/
• VisualHg--http://visualhg.codeplex.com/

TortoiseHg is a client tool that allows you to work with Mercurial via Windows Explorer as well as through a tool called TortoiseHg Workbench.  Of course, there are alternatives to TortoiseHg such as SourceTree (http://www.sourcetreeapp.com/), but I prefer to use TortoiseHg and will be using TortoiseHg for my examples throughout this article.

VisualHg is an add-in to Visual Studio which allows you to perform commits and other source control operations directly through Visual Studio.

First of all, let's get familiar with how a DVCS differs from a centralized source control repository such as Visual SourceSafe, Subversion or Team Foundation Server:

1. DVCS works be allowing each developer to set up their OWN source control repository on their local machine.  Therefore, commits initially occur to their own local repository.
2. The way in which most company/corporate DVCS systems work is by using a hosted repository such as BitBucket.org to host the centralized source code and each developer then clones the repository to their local machine.
3. Commits and other source control operations initially occur against the cloned repository.  
4. You can check your pending changes by performing a status operation. 
5. Just as with TFS, committed changes are identified as changesets.
6. When it comes time to get the latest version of changes from the hosted DVCS repository, you perform a pull operation. 
7. When you are ready to commit your changes to the hosted DVCS repository, you perform a push operation. 

Now once you have these tools installed and you are familiar with the Mercurial terminology, it is time to get started setting up your development environment!

First of all launch TortoiseHg Workbench:

Now, you will first have to set up your Username so that you can perform commits against your locally cloned repository as well as eventually perform pushes to the centrally hosted repository.  To do that, you can click on the File menu and select Settings.

On the Commit tab, enter your username for the DVCS repository and click on the OK button.

Once you have done that, it is time to begin cloning the centrally hosted DVCS repository to your local machine by selecting File-->Clone Repository.

The Source field will be the Url to your centrally hosted repository and the Destination field will be any path on your local file system.

Once you have entered these fields, you should be able to click on the Clone button to begin cloning the repository to your local file system.

Now that you have cloned the repository to your local file system, the nice thing about using a tool such as TortoiseHg is that you can even make edits directly through Windows Explorer and commit them to your locally cloned repository!!

If you see an .hgignore file on the file system, that file is used to ignore files that should not be committed to Mercurial source control such as temp files, binary files etc.  This file is simply a text file that can be edited to add additional files to ignore to suit your development needs.

Now, you need to configure Visual Studio to use the VisualHg plug-in for development.

From the Tools menu select Options.

Under Options, you will need to click on Source Control and change the Current source control plug-in to VisualHg:

Now, once you open the solution in Visual Studio, you will be able to perform source control operations directly from within Visual Studio:

F

Finally, when you are ready to commit the code back to the centrally hosted DVCS repository, you simply use the following icons in TortoiseHg Workbench to perform operations such as check incoming changes, pull incoming changes, check for outgoing changes and push outgoing changes:

NOTE: It is important to always check for incoming changes, pull incoming changes (and merge/commit to your local cloned repository) before pushing outgoing changes in order to ensure that the central repository gets updated properly.  Otherwise, you can end up with multiple heads (i.e. branches) of the main repository thus causing problems with your continuous integration build processes.    

That is all there is to it!!