Mercurial and BitBucket are easy to learn and use. It’s best to learn to use them securely from the very beginning.

Mercurial is one of two distributed version control systems that came into being as an answer to when BitKeeper pulled its proprietary, closed-source DVCS from free use by the Linux kernel project. The other was Linus Torvalds’ Git. Add Canonical’s Bazaar to the list, and you have the three most popular open source DVCSes in current use. Another major open source example is Darcs, a less popular but no less important contributor to the theory of distributed version control.

A DVCS is particularly well-suited to open source software development projects, and a simple, easy-to-learn interface is key to ensuring everybody can use it properly. Matt Mackall, the creator and lead developer for Mercurial (also known as hg, after the periodic table of elements symbol for the element Mercury), has given us a DVCS that is incredibly easy to learn and use day-to-day for common tasks, and that offers superb tools for branching, merging, cloning, and forking projects. In fact, key to the very concept of a DVCS as it tends to be used in the open source world is the fact that every developer basically has his own fork of the project within which he can make changes and save them to the local repository.

When combining his changes with the main project, he merges his local repository with the main project repository, and all is well with the world.

The Mercurial Website offers this explanation of its ease of use:

Mercurial sports a consistent command set in which most subversion users feel right at home. Potentially dangerous actions are available via extensions you need to enable, so the basic interface is easy to use, easy to learn and hard to break.

It is also fairly easy to maintain as a software project of its own, as (unlike its contemporaries Bazaar and Git) it sticks to a single, high-level, relatively dynamic programming language behind the scenes. Despite this language choice, hg is well regarded for the speed of its operations.

Git and Mercurial are both supported by very well-known Websites offered by online service providers — sites that provide free public project hosting, and can provide private project hosting for paying customers as well. The biggest such site for Mercurial hosting is called BitBucket and, as you might already know if you have read “A simple email filter: getlessmail,” I use it.

As of this writing, I have recently become the de facto admin for an open source Mercurial project repository on BitBucket, working with a group of people I have never met. The project’s purpose is to develop tools for use in formatting content to add to, a Website collecting open content for the Pathfinder Roleplaying Game. I have come to the conclusion that a very quick primer on using Mercurial securely with BitBucket would be a good idea. Rather than make it solely available to the project’s other developers, though, I decided to share it with my TechRepublic readership as well.

Installing Mercurial

Because of the wide variety of platforms on which one might use Mercurial, this article will not attempt to hold your hand through the process of installation. It should be available in the software management system’s archives for any major Linux distribution or BSD Unix system, and a couple of other open source operating systems as well.

For Microsoft Windows and MacOS X, you can also download an installer from the Mercurial Downloads page. Note that the TortoiseHG download makes Mercurial available through the standard Windows Explorer interface via right-click context menus, while the download marked only “Windows” is a standard hg installer ported to the MS Windows OS.

Setting up your BitBucket account

The first set of instructions for setting up a BitBucket account assume you are using a Unix-like system with SSH installed on it. This article will deal with some other options below.

  1. You should have a subdirectory within your home user directory called .ssh that contains files relevant to SSH on the machine. Check within this directory, and you should have a file named either or In either case, this is the public keyfile for your SSH account. If you do not have such a file, you can create it using the ssh-keygen command. Just enter that command, and follow instructions. For normal SSH use with a key, you will need to supply a strong password that you will (perhaps after a little practice) have memorized and be able to type with reasonable ease. Make sure the password is unique to your SSH key, just as you would keep a strong password unique to your root account and another unique to your OpenPGP keys.
  2. Go to the BitBucket site and click the big friendly “Sign up now” button — or just follow this BitBucket Sign Up link to go directly to the signup page if you do not want to look around the site first.
  3. You can sign up from there using OpenID, but with a good password manager at your disposal, I think it might be better for purposes of privacy to just use a unique set of log-in credentials for your BitBucket account. In that case, choose a username, enter an email address, and come up with a good strong password.
  4. Once you submit your account creation information, you should be taken directly to the homepage for your account. You should see a small box to the right-hand side of the page that says, “You don’t have any repositories yet. You can create one by following the link above.” First, however, we will address how to make sure you can use SSH with your SSH public key to connect to BitBucket using hg on a Unix-like system.
  5. Click on the Account link at the top of the page. This will take you to another page where you can change a number of account settings. The important part is the box on the right-hand side of the page that says “SSH Keys”. You can copy and paste the complete contents of your SSH public keyfile into the first text field there, but it will be easier for most users to click the Browse... button beside the second text field. Find the public keyfile for your SSH account and select it. Click the Upload key button at BitBucket once you have the path to your public keyfile in that second text field, labeled “Or you can upload your public key file here.”

Voila. Your BitBucket account is now set up for secure access via SSH. This is by far the most difficult part of the whole process of starting to use Mercurial with BitBucket in a secure manner.

Creating a BitBucket project repository

To create a new project repository on BitBucket is an exercise in simplicity. While it seems stunningly obvious how to create a repository, using BitBucket’s very clear user interface, a little extra explanation is almost never a bad thing.

  1. Get back to the homepage for your BitBucket account. You can do that by clicking BitBucket’s Home link at the top of the site while logged in, if you are not already there.
  2. This is where you click the + Create New link in the “Your repositories” box on the right-hand side of the page. This will take you to the “Create new repository” page.
  3. Fill in the name of the project for which you want to create a repository on BitBucket. This will also end up being the name of the directory in which you’ll keep your local repository for the same project, which is worth keeping in mind when you come up with a name for it.
  4. A simple description for the project is probably in order. It can contain whatever short description you like, and can be easily changed later. If you have a Website for the software project, or that is somehow associated with the project, you may enter its URL in the Website field.
  5. For free accounts, you can only have public repositories, so do not check the “Private” box. If you sign up for a paid BitBucket account, you can check the “Private” box to keep the contents of your project repository from being seen by the world at large.
  6. The “Issue tracking” checkbox determines whether BitBucket’s issue tracker (aka “bug tracker”) will be available to the project. It is a very good idea to have an issue tracker for open source projects.
  7. Finally, the “Wiki” checkbox determines whether you will have an active wiki for your project on BitBucket.
  8. When all your settings are tweaked the way you like, the “Create repository” button will confirm them.

You will then have a new Mercurial project repository on BitBucket.

Getting a local clone of the project using SSH

If you have a software development project directory already on your local system, keep it separate from this at first. The easy way to set up a local Mercurial repository for your BitBucket hosted project is to clone the empty project from BitBucket, then fill it with whatever you want it to contain. These instructions assume you already have the Mercurial distributed version control system installed on your system, and as a result have the hg command line tool available.

There is also a GUI interface available, but the command-line tool is quite flexible and its simplicity and speed make working with it a more efficient and friendly experience than using a GUI, at least for many people.

  1. Make sure your current working directory is wherever you want to deposit the directory that will house your local project repository. For instance, if you have a src directory located at /home/username/src on a BSD Unix or Linux-based system, and that is where you want your new linkifier project to go, you might enter the command cd ~/src to get there.
  2. Enter this command to clone the BitBucket hosted repository, where username should be replaced by your BitBucket account username, and project is the name of your project repository on BitBucket:
    hg clone ssh://

That’s it. As you can see, things just get easier and easier as you move from one step to the next. You can then move files into the project directory within your src directory, add them to version control in the local repository, and commit them locally; and then push your changes to the BitBucket project repository when they are ready to be made part of the official project.

Because your hg configuration is saved locally with preferences on your workstation (or wherever you keep your local project repository), any time you use hg commands to push changes to the BitBucket repository or pull them from it, you do not have to enter the connection protocol information and complete path, as it will simply use the same information from when you first cloned the repository (unless you configure it to behave differently).

Other options for talking to BitBucket with Mercurial

There are at least two other options for protocols to use to connect to BitBucket. One of them is unencrypted HTTP, but I would recommend against this as it may involve exposing your BitBucket username and password to the Internet in an unencrypted connection. Another is HTTPS, which I do not trust as much as SSH, but is at least an encrypted connection. For the use of HTTPS, you can skip the steps for making sure you have an SSH public keyfile and uploading it to BitBucket. Simply use this command format to clone the repository instead of the above clone command for SSH:

  hg clone

This may be especially handy for people working on systems that do not support Unix tools natively, such as Microsoft Windows workstations.

Basic Mercurial use

Rather than spend a lot of space doing something that has already been done to death elsewhere, I will simply refer you to the following sources for quickstart guidelines for basic use of the Mercurial toolset:

  • BitBucket’s Getting started with Mecurial provides useful BitBucket-oriented help for new Mercurial users. It does not present things in the most ideal order for getting started, in my opinion, but can serve as a useful quick reference document.
  • Joel Spolsky’s Hg Init has become the de facto official quickstart guide for Mercurial, and provides some useful information about the philosophy behind the design and use of the hg tool. As an MS Windows guy, Spolsky also takes a slightly more Windows-oriented approach to presenting his quickstart than this article.
  • Mercurial’s own help documentation, suitable for quickly familiarizing people familiar with the concept of distributed version control. Use the command hg help to get started, and have a look at the manpage for hg by way of the command man hg for more information.
  • My simplified help documentation for the linkifier project is, like this article, specific to using Mercurial with BitBucket over an encrypted connection. It does less hand-holding than this article, but might be a faster introduction for technically-oriented readers. If you want to use this resource, I recommend starting by reading the README file, which serves as a guide for the other help documentation in the help directory for the linkifier project.