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)
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.
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
When the workbench launches, what you’ll see is something like this.
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.
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.
Your window should look like this
STEP 4 CLONE TO A LOCAL REPOSITORY
Create a folder to house the local repository. I created a folder here D:\hg\visioautomation
Launch the Hg Workbench and click File > Clone Repository
The Clone dialog will appear
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.
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
Once it is done this is what you should see…
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.
The TortoiseHg Settings dialog will appear.
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.
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.
Most of the time I live in the Commit and Synchronize views.
STEP 7 OUR FIRST COMMIT
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.
All we need to do is click the Refresh button under the file menu.
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
Enter a commit message…
And click Commit
Because this file was previously unknown – TortoiseHg will confirm that we do want to add the file. Just click Add.
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 …
It’s worth it to get familiar with using the Synchronize view
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.
This brings up the Post Pull Behavior dialog.
Select Update and click Save
Now the button says “Post Pull: Update”
To amuse ourselves lets do a pull to make sure have all the latest changes in the remote repository.
You can see from the output log that there were no changes in the remote repository
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.
We’ll be asked to confirm the push. Click Yes.
And, at this point we’ll be asked for a user and then a password.
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…
The Security dialog will launch. Enter the appropriate Username and Password and click Save.
Now try Pushing again …
We still get the confirmation dialog.
But now we were not asked for the username or password and the push succeeded.
The fact that the push worked is visible in two ways: in the Output Log and in the Status bar
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.
- 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.