Mercurial on Windows

Here’s a way to get Mercurial running on Windows that’s simpler than the other ways I’ve seen (it avoids Cygwin).

Starting with the archive

  1. Obtain the class private key in Putty format (it might be emailed to you as classes.ppk, or you can convert the original key by opening it in PuTTYgen and saving it in ppk format without a password)
  2. Install TortoiseHG.
  3. Open the file C:\Users\YOUR_NAME\mercurial.ini in Notepad (create it if it doesn’t exist).  Add these lines (substitute with your name and the correct key location):
    [ui]
    username = Your Name <YOUR_NAME@mit.edu>
    ssh = TortoisePlink.exe -ssh -2 -i "C:\Users\YOUR_NAME\Downloads\classes.ppk"
    editor = notepad

    Save the file and close.

  4. Right click on the Desktop or anywhere you want to check out the class directory, select TortoiseHg then Clone.  For source, put (this is for 2013, but you can pick the last two digits to get the correct year):
    ssh://hg@fab.cba.mit.edu:846/863.13

    Click “Clone”.

Using the archive (summary)

You should be done and able to add files and push them by right-clicking and using the options in the TortoiseHg menu. You can also use the command prompt by running hg commands in that directory (hg should now be on the path).  Remember the two commandments for the class archive:

  • Don’t add large files to the repository, since it adds up over time and over students.  Aim for one megabyte of information a week.  Check before you add and commit, since you can’t undo pushed commits.
  • Don’t create multiple heads (that is, don’t force a merge with hg push -f ).  Commit your local changes, then pull, update, merge, and commit.  Then push the merged snapshot back.

Common initial problems (and solutions):

  • Clone fails with error messages like “TortoisePlink.exe not found”.  Reboot (or at least log off and log in again) to make sure the Tortoise/Mercurial install changes are active.  Make sure “hg” works on the command prompt.  If not, try reinstalling TortoiseHG.
  • Clone fails with error messages like “unsuitable response from hg” or it times out.  It can’t talk to the server correctly.  Is your internet working, or are you behind a restrictive firewall (some of the MIT GUEST networks may be too restrictive)?
  • Clone asks for a password to access fab.cba.mit.edu.  This means it’s not finding your certificate, or it doesn’t know to look for it.  Is the certificate file (e.g. classes.ppk) in the location you said it was in mercurial.ini?  Is the mercurial.ini file actually named mercurial.ini?  Depending on your configuration, Windows might hide the file extension or name the file something like mercurial.ini.txt.  This won’t work, since Tortoise doesn’t know to look at that file.  It needs to be exactly mercurial.ini, so rename it appropriately.