Setting up TortoiseHg for Fab Academy

I am taking part in Fab Academy 2013, and the first assignment was to get setup on the course website using Mercurial, a version control system. I'd heard of it before but not ever really looked into it in detail. I was surprised how straightforward it was in the end to get it going under Windows and with a GUI, having been deterred slightly by others' advice, and having tried and failed to get GUI vresion working on OSX a couple of weeks ago. To be honest I only really tried it this way because I was ill at home on the laptop. Anyway:

I started with a download of TortoiseHg, a version of the Mercurial application for Windows, with a GUI (Mercurial typically is run from the command line). Here is the download page.

Hg is the chemical symbol for Mercury. It took me pitifully long to realise this.

Having installed that, I went right ahead and tried to clone from the Manchester server. Cloning is copying a whole project ('repository') from another location to your local computer. We are synchronizing our work with Manchester, and they are subsequently synchronizing with Boston MA. I found the server address in the documentation that Eddie in Manchester sent us. Having already attempted to setup Mercurial once, I sort of knew what I was looking for, here it is:

ssh://fab@82.109.119.66:/fabacademy/academy.2013

So I started up TortoiseHg and chose File/Clone Repository. I then pasted that server address into the Source field and chose a new folder on my desktop for the destination (this can be moved around later). Then I clicked Clone, and Detail for more verbose status updates. I like how Tortoise tells you what the equivalent Hg command would be in the command line for what you are doing (bottom text field).

Now, the ssh at the start of the server address indicates that this is to be connected to using a secure shell (a security protocol) which requires a key. I hadn't set the keys up yet so naturally I could not connect at first - I was asked for a password. Not ideal, so I cancelled that.

I couldn't find anything in the program settings to do with SSH so naturally searched the web for "tortoisehg ssh keys" and soon found a lead. I needed to run another wee program called Pageant that, as luck would have it, comes with TortoiseHg. Pageant is simply an agent for looking after SSH keys. It is in the TortoiseHg installation folder and runs in the System Tray (the bit near the clock in the Windows taskbar). 

All I had to do was run the pageant.exe, double click its icon in the system tray and choose Add Key.

Problem: the keys I had been emailed were not compatible with PuTTY, the SSH module of TortoiseHg. So I needed to convert one of them. Luckily there is a wee program for doing that very thing here. Now, we were emailed a public (ending.pub) and a private SSH key (ending in nothing). Seemingly I only had to load the private key into the converter, and save it as a .ppk file - in fact I'm not sure I even need to use the public key at any time? Anyway, I keep them all in a folder and point Pageant at the .ppk. It comes up in Pageant as an amiable string of gobbledigook.

Now I was able to clone, which is great because you get to see the cool flowchart thing that tracks the various revisions everyone is making!

At this point I thought I'd better fall back in with the instruction Manchester had sent out, and edit the configuration file for the repository. This is stupidly easy in Tortoise by going to File/Settings, then choosing the tab corresponding to the repository you just cloned (you have to have the repository open in Tortoise for this to work)  and choosing Edit File. Up pops the hgrc file. I inputted the following:

[paths]

Default: = ssh://fab@82.109.119.66/fabacademy/academy.2013

[ui]

username = First Last 

[hooks]

changegroup = hg update >&2

Where First Last is my name and user@machine.domain is my email address. I believe this is just for signing off changes so people can get in touch with you if they want.
I omitted to put in the line that Manchester included that points to the SSH keys as Pageant was now doing that for me.

I then continued with the generic instructions for getting to know Mercurial.

Later, when committing some changes, I was asked to choose a username which I did in File/Setting/global settings tab under Commit and Username - my name was in the drop down menu already so I selected it.

I don't know how or why, but this setup seems to work without me specifying a SSH port - I don't know where to do this, so I'm keeping my fingers crossed that it won't become a problem!