Skip to content

Starting with Mercurial, BitBucket and SourceTree on Mac

This is a quick step-by-step tutorial on starting with Mercurial and BitBucket on Mac. This tutorial was done on Mac OS 10.8.2.

Install Mercurial

The easiest way to do that is to download and install the Mercurial 2.5.4 for OS X 10.8 binary package from the official Mercurial site. After downloading the file unzip it and open mercurial-2.5.4+20130405-py2.7-macosx10.8.mpkg.

Verify Mercurial Installation

Open Terminal and type hg –version.

hg --version
Mercurial Distributed SCM (version 2.5.4+20130405)
(see for more information)

Copyright (C) 2005-2012 Matt Mackall and others
This is free software; see the source for copying conditions. There is NO

Install Mercurial Keyring Extension

In Terminal:

sudo easy_install keyring
sudo easy_install mercurial_keyring

Next, add these lines to .hgrc (in your home directory):

mercurial_keyring =

Now Mercurial will store and use user credentials to/from the Mac OS keychain.

Configure BitBucket User

There are a few ways to do this, but the best is via [ui] and [auth] sections in .hgrc (in your home directory). Your final .hgrc file should look like this:

username = Valentin Kantchev <youremail@<span class="oe_displaynone">null</span>>

[auth] = = yourusername


Install Atlassian SourceTree

Go to and download SourceTree for Mac. At the time of this writing the latest version of SourceTree was 1.5.8. SourceTree for Mac comes packaged as a dmg file – after you open the dmg file you install the app the normal Mac way – by dragging into your Applications folder.

Configure SourceTree

I recommend configuring SourceTree to use the system Mercurial. That way you get consistent Hg experience when working in Terminal and in the SourceTree GUI. To do that, run SourceTree and press “Command + ,” to open Preferences and then click Use System Mercurial.


Clone a BitBucket Repository

In the SourceTree Bookmarks window:

  1. Click on the Add Repository button.
  2. Enter the remote repository url and the local repository folder.
  3. Click Clone

sourcetree-add-repository sourcetree-clone-repository sourcetree-repository-bookmark