» Project Kenai Documentation and Training    » How Do I ...    » Using Mercurial on Microsoft Windows Systems

Setting Up Mercurial to Use SSH on a Microsoft Windows Machine

Before reading this section, make sure you've installed the Mercurial client. As described at About Mercurial, you can download the Mercurial client as an installable binary from http://www.selenic.com/mercurial/wiki/index.cgi. Use the default settings and ensure that the installer adds the Mercurial path to the system PATH environment variable.

In addition, these instructions assume that you've generated an SSH key with PuTTY as described at Generating and Using an SSH Key on a Microsoft Windows Machine.

Note: Thanks to Oliver Reeves (OJ) for his blog Setting up Trac, Mercurial, and SSH on Windows, which was very helpful in writing this page.

To use an SSH key with Mercurial that you've generated with PuTTY tools, you need to configure Mercurial to use the PuTTY tools when using SSH. The Mercurial configuration file you'll use to do this is typically called .hgrc. On Windows it can also be called Mercurial.ini. The file is located in your home folder, for example, C:/Documents and Settings/your-username. If you don\u2019t know where your home folder is, open a Command window and type echo %USERPROFILE% to see the path.

If you haven\u2019t set up your Mercurial configuration yet, chances are the configuration file doesn\u2019t exist, and you\u2019ll have to create it. Create a file call either .hgrc or Mercurial.ini in your home folder and open it in a text editor.

For example, in Cygwin, you could create the file with the following command:

 ~ cat > .hgrc

Type Ctrl-C to close the file and save it, and then you can reopen it in Notepad to edit it.

Here is what the ssh lines in the file would look like:

 [ui]
 ssh = plink -ssh -i "C:/path/to/key/id_rsa.ppk" -C -agent

This line tells Mercurial to use the plink program. This program comes with PuTTY and is a command-line version of what the PuTTY program does behind the scenes. Here's what the parameters mean:

• -ssh: Indicates that Mercurial should use the SSH protocol.
• -i \u201cfile.ppk\u201d: Specifies the location of the private key file you want to use to log in to the remote server. Change this to point to your local putty-compatible .ppk private key. Make sure to use forward slashes for the path separators.
• -C: Enable compression.
• -agent: This tells plink to talk to the pageant utility to get the passphrase for the key instead of asking you for it interactively.

You're now ready to use Mercurial with SSH.