Using SSH

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

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.

Windows Users: You can create private/public keys using PuTTYgen. This is not described in further detail here.

Enabling Compression

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

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

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

Host bb
  Compression yes
  HostName bitbucket.org

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.