I’ve received a lot of questions both internally and externally about using Mercurial and TortoiseHg due to my original post on this blog. Seems like Mercurial is getting very popular and there’s a lot of interest coming getting up-to-speed with it quickly. In this post I’m going to focus on those people who need to get working quickly on Windows with TortoiseHg. For more informational about Mercurial I suggest everyone start by reading Hg Init by Joel Spolsky

STEP 1 AQUIRE TORTOISEHG 2.0

Just go to http://tortoisehg.bitbucket.org/ and download the x86 or x64 version depending on which version of Windows you are using. The current version of TortoiseHg I will using for this blog post is TortoiseHG 2.0.4 (it bundles Mercurial 1.8.3)

image

After installing, you’ll want “TortoiseHg Overlay Icon Server” (you can see the icon in the notification area) to be working. Just log-off and log-on and it should be working.

image

 

STEP 2 GET THE MERCURIAL CLONE URL FOR THE REPOSITORY

In this demo I’ll use my “visioautomation” project on CodePlex

The CodePlex project is here: http://visioautomation.codeplex.com/

And the Mercurial Clone URL for the project is https://hg01.codeplex.com/visioautomation

 

STEP 3 CONFIGURE THE WORKBENCH UI

Start the TortoiseHg Workbench: Right click on the folder and click Hg Workbench

image

When the workbench launches, what you’ll see is something like this.

image

Notice the window on the left called “Repository Registry”. It’s useful to have this up. If you don’t see it you can enable it via the view menu.

image

You’ll also want to see the Output Log. Again, enable it via the view menu. I recommend always seeing the output log because you will miss important and useful information if you ever get an error or warning.

image

Your window should look like this

image

 

STEP 4 CLONE TO A LOCAL REPOSITORY

Create a folder to house the local repository. I created a folder here D:\hg\visioautomation

image

Launch the Hg Workbench and click File > Clone Repository

image

The Clone dialog will appear

image

Set the Source field to the clone URL. Set the Destination field to the local repository path (in this case “D:\hg\visioautomation”). Then click Clone.

image

As it is performing the clone you’ll notice it says “Running…”. If you want to more clearly see what is going on just click the Detail button

image

image

Once it is done this is what you should see…

image

Notice that “visioatuomation” appears in the Repository Registry window.

STEP 5 CONFIGURING THE REPOSITORY SETTINGS

Typically we’ll at least want to ensure that a specific username is used for commit operations.  Right-click on the repository settings in the registry and click Settings.

image

The TortoiseHg Settings dialog will appear.

image

Notice there are two tabs: One is for global settings, and then you’ll have a tab for every repository in the registry. I generally do not touch the global settings, but instead configure repository-specific settings.

Typically the change we need to do here is to specify the Username for commit operations. Select Commit in the list and choose an appropriate Username - In my case I use my email address – and then click OK.

image

STEP 6 IMPORTANT WORKBENCH VIEWS

Under the View menu you can see there five views: Revision Details (which is currently enabled), Commit, Synchronize, Manifest, and Search.

image

Most of the time I live in the Commit and Synchronize views.

 

STEP 7 OUR FIRST COMMIT

image

image

You can enter a commit message in the green area (the green is only visible if you have clicked in that region). And of course there is a big Commit button on the right.

Let’s do an initial commit – I’ll add an empty text file called readme.txt at this location: D:\hg\visioautomation\reademe.txt

If I go back to the workbench and look at the Commit view – nothing has changed. It does not indicate that there is a new file.

image

All we need to do is click the Refresh button under the file menu.

image

image

You can see that now is aware of the readme.txt file in the repository. To commit this change, enable the checkbox next to the file

image

Enter a commit message…

image

And click Commit

image

Because this file was previously unknown – TortoiseHg will confirm that we do want to add the file. Just click Add.

image

image

Modifying or deleting a file works similarly – simply make the changes you want, refresh the Workbench and commit.

STEP 8 PULLING

Even though the default tool bar includes icons for pushing and pulling …

image

image

 

image

It’s worth it to get familiar with using the Synchronize view

image

image

 

Typically, when I pull changes into my local repository I always want to do an update operation immediately afterward. The Synchronize view makes it easy to configure this behavior by default.

In the middle of view, you’ll see a button that says “Post Pull: None”. Click it.

image

This brings up the Post Pull Behavior dialog.

image

Select Update and click Save

image

Now the button says “Post Pull: Update”

image

 

To amuse ourselves lets do a pull to make sure have all the latest changes in the remote repository.

image

You can see from the output log that there were no changes in the remote repository

image

 

STEP 9 PUSHING

At this stage I’ve made a commit to my local repository but have not PUSHed the changes back up. We will do this now.

image

We’ll be asked to confirm the push. Click Yes.

image

 

And, at this point we’ll be asked for a user and then a password.

image image

Of course, its simpler to have TortoiseHg just do this for us automatically. So I cancelled this PUSH.

And now we’ll configure TortoiseHg to remember the username and password to use.

Click on the Lock Icon…

image

The Security dialog will launch. Enter the appropriate Username and Password and click Save.

image

Now try Pushing again …

image

We still get the confirmation dialog.

image

But now we were not asked for the username or password and the push succeeded.

image

The fact that the push worked is visible in two ways: in the Output Log and in the Status bar

image

 

NOTE: If you are wondering about the pink line that says “abort: response expected” – this is OK – remember I said a cancelled the PUSH when it asked for my username and password. The consequence of pressing the cancel button was that the push operation was aborted.

PARTING THOUGHTS

  • I’m a complete convert to DVCS now – and especially Mercurial because it seems simple and has good integration with Windows and Visual Studio (via VisualHg). I’m switching all my codeplex projects over from TFS to Mercurial.
  • FYI, I am also starting using PlasticSCM this week – a product which has the benefits of DVCS combined with features that an enterprise organization needs. Once I have used it for a bit, I’ll blog more about my experiences with it.