mercurial with ssh setup on windows

May 21, 2009

Mercurial is awesome. Mercurial over SSH is even awesomer. Here’s a way to set it up on Windows using PuTTY.

Mercurial over SSH is a safe way to transfer your files to a private repository. A good place to host your repository is bitbucket.

Here is a list of files you need:

1. Install mercurial. The default options are good, especially make sure you leave “Add the installation path to the search path” option checked in the last dialog.

mercurial install, add to path

mercurial install, add to path

2. Copy putty.exe, plink.exe and puttygen.exe into the mercurial install folder: C:\Program Files\Mercurial. (This is to ensure that the patty utilities are in the search path. You can of course place them in another location, just make sure to add that folder to the search path.)

putty in mercurial folder

putty in mercurial folder

3. Find out what your home directory is. On Vista it’s something like C:\Users\lajos, on XP C:\Documents and Settings\lajos. The easiest way to make sure is to start a command prompt (hit the Windows button and “R” for the run menu, and type cmd). In the command prompt type

echo %USERPROFILE%

and hit enter. This prints your home directory:

run cmd

run cmd

user folder print

user folder print

4. Start puttygen.exe from the mercurial folder and select SSH-2 DSA for the type of key to generate:

make ssh-2 dsa key

make ssh-2 dsa key

5. Hit the “generate” button. You will have to move your mouse cursor around in the empty area to create randomness for the key… it’s a pretty cool idea. Once your keys are done, you can copy and paste the public key from the text area into your bitbucket account or email it to your repository administrator so they can grant you access. (Make sure you select all the text from the window.)

copy public key

copy public key

It’s also a good idea to save the public key if you need to use in another repository. Hit the “save public key” button and save the file in your user folder, call it something like mercurialPublicKey:

save public key

save public key

6. Save the private key in your user folder (the folder you looked up earlier from %USERPROFILE%.) Make sure to save it without a passphrase (even though you will get a warning about it- make sure to not give this file to anyone, ever, it’s like your ATM card with the pin code written on it.) Hit the “save private key” button, browse to your user folder and call the file mercurial:

save private key

save private key

7. Copy the mercurial.ini template file in your user folder (that folder gets used a lot, huh?) Open it in your favorite text editor and

  • replace YOUR_NAME with your name (this will show up on your commits)
  • replace YOUR_EMAIL with your email
  • replace USER_FOLDER with your home directory, but instead of back slashes, use forward slashes

(Don’t worry about the lines that start wih “#”, those are comments that are ignored.)

Example for Vista (comments removed):

[ui]

username = lajos kamocsay <lajos@night.com>

ssh = plink.exe -i "C:/Users/lajos/mercurial.ppk"

Example for XP:

[ui]

username = lajos kamocsay <lajos@night.com>

ssh = plink.exe -i "C:/Documents and Settings/lajos/mercurial.ppk"

8. Almost done, just need to make sure that the server is added to putty’s known hosts list. If you skip this step, mercurial will hang without any error messages. In the command prompt type and run:

plink ssh://hg@bitbucket.org

Replace bitbucket.org with your repository’s server name. You should see something like this:

add server to known hosts

add server to known hosts

Hit “y” to add the server to the known host.

9. All done! In bitbucket you can see the SSH clone command in the repository view (you might have to click on the SSH link):

bitbucket SSH clone

bitbucket SSH clone

Here’s a pretty good mercurial tutorial if you are just getting started with mercurial.

Have fun and congratulations for finally leaving the deep dark past os cvs, subversion, or whatever other centralized version control system you were torturing yourself with.

4 Responses to “mercurial with ssh setup on windows”

  1. Thanks for this detailed post. I found one serious time-saving gem

    “make sure that the server is added to putty’s known hosts list… plink ssh://hg@bitbucket.org”

    I’ve been using Bazaar (bzr) and Git (git) on Windows for a while now and the additional ease of setup they both provide is a bundled ssh wrapper. Hence whenever I connect to a new server with bzr or git, I would get the prompt to add the server to my trusted list.

    This is not the case with Mercurial (hg); you have to wire it through plink and therein lies the trap. I almost gave up on hg (at least on windblows) when it kept hanging each time I would try to connect to bitbucket.org over ssh.

    Fast forward through a bunch of reads and re-reads of bitbucket and Hg docs, a bright string of cussing and calling down the pox upon the collectively (un)deserving heads of windblows and hg developers. The fix? Some rookie-level google-fu that led me to your excellent writeup here and BAM! I’m in hg + bitbucket heaven.

    Massive respec’

  2. [...] http://www.codza.com/mercurial-with-ssh-setup-on-windows [...]

  3. Hi there,

    Thanks for a great tutorial, saved me a lot of time!

    For some reason I found that the following worked for me, while your version didn’t:

    ssh = TortoisePlink.exe -ssh -i “C:\\Users\\David\\mercurial.ppk”

    Note that TortoisePlink.exe is a wrapper (or something like that) created by TortoiseHG guys, which was designed to provide Windows-friendly outputs for plink.

    I genuinely wonder how people managed to sort out such issues in pre-internet times!

    David.

  4. Sweet, awesome tutorial - thanks!!

Leave a Reply