If you haven’t read the news, Umbraco is moving it’s repository format from TFS to Mercurial today! The Umbraco post lists quite a few links to start learning about Mercurial and how it works and I definitely recommend reading them!  Aaron from the Core team has also put up some blog posts:

• Umbraco And Mercurial How to Contribute
• Mercurial 101 as an Umbraco Developer

This post is going to show you how to get up and running quickly with Mercurial and the Umbraco source using 2 UI tools: TortoiseHg and VisualHg.  So first thing is first, make sure you download these 2 applications and get them installed.

Using TortoiseHg

Initial setup

If you are familiar with TortoiseSVN then this should seem reasonably similar to that. TortoiseHG, like TortoiseSVN, is an application that is accessed by a context menu in Windows Explorer. An important thing to note about TortoiseHg is that there’s settings, both on a global level and on a repository level. If this is the first time you’ve used TortoiseHg, then it might be a good time to set up some global defaults:

Global settings can be found by right clicking a folder –> TortoiseHg –> Global Settings

 

Here’s some defaults that I recommend setting up on a Global level:

Change the default Diff tool

This is my own personal preference, but the default diff tool is called KDiff3 which I find horribly ugly and difficult to use… up to you though. I’m currently a fan of DiffMerge which is an awesome free diff tool that does both file and folder diffs, plus it looks nice and is extremely simple to use. Once you install a default diff tool it should show up in the drop down lists for: Three-way Merge Tool and Visual Diff Tool

Set your default username

Again, you don’t have to do this but since my username for most of the Mercurial accounts is the same, I set it here. This is also the name that will be associated to any change sets that you commit.

Clone the source

Ok, time to get the code! First thing is to create a folder where you want to store the repository. Since Mercurial is a DVCS you need to actually download the entire repository (aka CLONE). This will download all changesets, branches, tags, etc…. This might sound like a lot but when dealing with blocks of code, it's generally relatively small (NOTE: there are extensions and tricks in Mercurial that allow you to not have to clone the entire repository, but we’ll let you research those! ). Once your folder is created, right click –> TortoiseHg –> Clone…

The only thing that is required to clone the repository is to enter the source address, as seen below:

Once you clone the source, this will automatically update your latest working folder the the ‘Tip’ which is the latest committed change set in the repository, however there’s an option listed on the Clone dialog to disable this behavior if you don’t want that to occur (as seen above). This can be useful if you want to clone a repository but have your working copy updated to a specific revision or branch. In this example, we’ll update our working copy manually since there’s a few active branches in the Umbraco codebase and we’re not sure which one the ‘Tip’ will be. Once the clone is complete, you can either use the Update context menu option, or use the Repository Explorer.

Update Dialog

The update dialog is a quick way to update your working copy to the latest revision of a specific branch or tag. This is pretty straight forward, just select the branch/tag you want to work from and click Update. NOTE: there are a couple of advanced options:

• Discard local changes – don’t leave this checked unless you mean it. This will remove any local changes you may have made is completely replace them with what's in the branch
• Always merge – a pretty good idea to have this checked so the merge dialog will show when it detects conflicts
• Always show log – if you want to see some log info, check it

Repository explorer

The Repository explorer is probably where you’ll spend most of your time working with Mercurial (at least I do). From here you can run most of the commands that you need: Pull, Update, Commit, Push & Merge though there’s a few ways that you can do each one of those from the various menus. The repository explorer shows you the history of all of the checkins including date/time, the user who did it, which files were modified/added/deleted and will even show you a nice diff/patch view of each changed file.  The UI gives you a bunch of tools to filter the list of change sets that are visible such as filtering by branches or searching for revisions, users, etc…

Merging

Merging in Mercurial is actually really easy, as compared to some other version control systems and it happens reasonably often if more than one person is working on the source at one time (which is generally the case). Merging can easily be done from the Repository Explorer and you’ll know when you have to merge. Here’s when

• You try to push your committed changesets to the server and TortoiseHg starts complaining about create multiple remote heads in the repository. This means that you need to do a pull and get the latest revisions.
• Or, you’ve done a pull and can see that there’s newer revisions in the graphs

So all you need to do is open the Repository Explorer (as seen above), right click the revision that you want to merge with and click “Merge with”. If there’s any conflicts, it will launch your Diff tool. Once you’ve merged, it will ask you to commit the changes which you can cancel if you want to manually fix any conflicts.

Local Repository Settings

As mentioned before there’s both global and local repository settings. To get to the local settings:

Repository Explorer –> Tools –> Settings

Save your repository password

One thing I always do so that TortoiseHg doesn’t prompt you every time is save the password for your repository. You can do this from the local repository settings –> Synchronize –> select the ‘default’ item in the Remote Repository Paths (this should have been automatically created when you first cloned the repository) and select edit.

Using VisualHg

VisualHg is a source control plugin for Visual Studio which does what you would expect:

• Automatically ensures that files are added to source control when you create a file
• Automatically handles renaming/moving files in source control when you move/copy files in the solution explorer
• Has handy colored icons for each file to show you what’s changed, renamed, etc…
• And additional context menu items for items in your solution explorer which are quick links to the TortoiseHg interface:
• Commit
• Launches the commit dialog
• Status
• Shows you the history of particular files, allows you to revert to specific revisions, etc…
• History
• Launches the Repository Explorer
• Synchronize
• Launches the Synchronize dialog allowing you to Push/Pull your changes from CodePlex
• Update
• Launches the Update dialog
• Diff
• Launches the default Diff tool

Activating VisualHg

Since you might already have TFS (or other) configured as your primary source control plugin for Visual Studio, you might need to tell Visual Studio to you VisualHg instead when working in the Umbraco repo. This is really easy and you don’t have to restart Visual Studio either. Just go to:

Tools –> Options –> Source Control –> Select VisualHG from the drop down list

That’s it!

Final thoughts

There’s a TON of functionality in Mercurial and I mean A LOT. Aaron’s posts talk a lot about the command line and it’s good to become familiar with it since if you want to do more complicated things like using the extensions (which can be enabled on the Global or Local Repository settings), then this nearly all has to be done from the command line. There’s also a lot of functionality that you can do with these UI tools that I haven’t talked about such as branching, creating patches, exporting bundles, serving your own repository server over a web port, shelving changesets, and lots more. So go explore!