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:
- mercurial installer from mercurial’s windows download page (get the latest version, 1.2.1 at the time of writing)
- the following programs from the PuTTY download page:
- my mercurial.ini template:
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.
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.)
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
and hit enter. This prints your home directory:
4. Start puttygen.exe from the mercurial folder and select SSH-2 DSA for the type of key to generate:
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.)
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:
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:
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 <firstname.lastname@example.org> ssh = plink.exe -i "C:/Users/lajos/mercurial.ppk"
Example for XP:
[ui] username = lajos kamocsay <email@example.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:
Replace bitbucket.org with your repository’s server name. You should see something like this:
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):
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.