Using SSH

(If you haven't read the introduction, "Getting started with Mercurial", we suggest you do so now.)

It's important that you use the username 'hg' and not your own username when using SSH.

Using SSH with Bitbucket

Mercurial supports pulling and pushing over HTTP, but in some cases, e.g. very large repositories, it is usually better to use SSH. Bitbucket offers full SSH support, and is able to compress data being sent, so you can push and pull faster.

If you want to use SSH with Bitbucket, you must set up your "public key" in your account settings. This allows us to uniquely identify your account when connecting.

Getting Started

To get started with SSH, make sure that you have an SSH client.

$ ssh -v
OpenSSH_4.7p1, OpenSSL 0.9.7l 28 Sep 2006
...

The format to use with Mercurial is ssh://hg@bitbucket.org/username/reponame/. For example:

$ hg clone ssh://hg@bitbucket.org/jespern/testrepo
...

If you clone this way initially, Mercurial will automatically retain this path for later use, so you can simple type hg pull and hg push.

Setting up your Public Key

If you are on Linux or Mac OS X, you probably already have a public key. Check if the file ~/.ssh/id_rsa.pub or ~/.ssh/id_dsa.pub exist. The difference between the two is the encryption scheme used, and we support both, so either will do.

Let's look at the contents:

$ cat ~/.ssh/id_dsa.pub
ssh-dss AAAAB3NzaC1kc...wtAUFQ= jespern@cantor

We need the whole key, so don't omit any of the leading ssh-dss stuff.

If you do not have either of the two files, we need to create one. We do that with ssh-keygen:

$ ssh-keygen 
Generating public/private rsa key pair.
Enter file in which to save the key (/Users/jespern/.ssh/id_rsa): 
Enter passphrase (empty for no passphrase): 
Enter same passphrase again: 
Your identification has been saved in /Users/jespern/.ssh/id_rsa.
Your public key has been saved in /Users/jespern/.ssh/id_rsa.pub.
The key fingerprint is:
d1:36:66:21:13:41:15:87:37:45:2f:c4:0c:b7:7e:70 jespern@cantor

You should now have a file named ~/.ssh/id_rsa.pub and you can go ahead and update your account settings.

Ubuntu Users:

chmod 644 ~/.ssh/id_rsa.pub
ssh-agent bash
ssh-add

Windows Users: You can create private/public keys using PuTTYgen. This is not described in further detail here. Also, be sure to add your private key with pageant like this:

> pageant id_rsa.ppk

Enabling Compression

By default, Mercurial does not use compression when sending or retrieving data via SSH. In some cases, enabling compression can speed up things drastically.

There are two ways you can do this:

• Tell Mercurial which SSH command to run
• Specify compression in your ~/.ssh/config file

To tell Mercurial to use compression, edit your ~/.hgrc file to look like this:

[ui]
ssh = ssh -C

To specify it in your SSH config file, edit ~/.ssh/config to look like this:

Host bb
  Compression yes
  HostName bitbucket.org
  User hg

In this case, we also set up an alias bb to point to bitbucket.org, which makes it possible for you to use a shorter name as well.

On Windows, if your SSH access is already going through TortoisePlink.exe, which is the likely case if you've installed TortoiseHg (to confirm this run hg showconfig and check the ui.ssh line) then edit your ~/.hgrc (or your Mercurial.ini as explained by hg help config):

[ui]
ssh = "C:\Program Files\TortoiseHg\TortoisePlink.exe" -ssh -2 -batch -C

Using Multiple Accounts

If you have multiple BitBucket accounts, you need to generate a new public/private key pair for each account.

Don't overwrite your old key!

You'll also (on *nix and OS X) set the permissions on the new key to be very restrictive to keep ssh from complaining (and not working).

 # ssh-keygen -t dsa -f ~/.ssh/newacct
 # chmod 600 ~/.ssh/newacct*

Upload that new key (/.ssh/newacct.pub) to your BitBucket account, then, edit the .hg/hgrc file of the project to tell it to use the new key. While you're at it, you might as well tell it to use compression as above by adding the -C switch as well.

[ui]
ssh = ssh -i ~/.ssh/newacct -C