Set up Git and Mercurial (Mac OSX)

To use Bitbucket, you need to install a DVCS tool on the computer where you write your code. Typically, this computer is a machine physically close to you like your home or work computer. This is your local machine or system. You also might write or deploy code to a remote machine – for example a lab computer or a server in a data center. You may also need a DVCS tool on that machine too. This tutorial refers to the typical case, your local system, but the instructions are the same for both cases.

Bitbucket supports two DVCS tools, Git and Mercurial. These tools run on all modern operating systems.  For Git, Bitbucket supports 1.6.6 or later and Mercurial version 1.7 or later. Mercurial also requires (depends on) the Python programming language. The installation process takes care of making sure you get the correct version of Python.

Since you can use both Git and Mercurial on the same machine, this page shows you how to install both because you need both to complete this tutorial.  If you already have these tools installed, skip the instructions and go to the next step in the tutorial.

Windows or Linux User?

Microsoft Windows users see this page.
Linux users see this page.

Step 1. Install Git

If you are using a Mac, you may already have Git. To find out, open a terminal and enter git --version.

$ git --version
git version 2.3.2

If you receive a version number, as shown in the previous example, great! You have Git already and can continue to the next step. If not, install Git.

If you run into issues while following these instructions, make sure you have root access (sudo) on the system where you want to install Git.

  1. Download the Git installer from its official website.  
    The installer is a DMG file. 
  2. Double-click the DMG to expand it.
  3. Double-click the PKG file to install it.
    The Git installer launches.
  4. Follow the prompts to install Git.
  5. Open a terminal on your system.
  6. Verify the installation was successful by typing which git --version at the command line.

    $ git --version
    git version 2.3.2

    Depending on the version you install, the command line may return a different version.

Step 2. (Optional) Install the git-credential-osxkeychain helper

Bitbucket supports pushing and pulling over HTTP to your remote Git repositories on Bitbucket. Every time you interact with the remote repository, you must supply a username/password combination.  Instead of supplying the combination with every HTTP call, you can store these credentials in your OSX keychain provided you have the git-credential-osxkeychain helper added to Git.  

The helper asks for your username/password on the first Git operation and then stores the credential. Future operations won't require you to supply a username/password combination. To install the helper, open a terminal window on your local system and do the following:

  1.  Check if you have the helper installed by determining if you get a usage statement for it.

    $ git credential-osxkeychain
    usage: git credential-osxkeychain <get|store|erase>

    If you receive a usage statement, skip to Step 5.  If the helper is not installed, go to the next step.

  2. Download the git-credential-osxkeychain software to your source with curl;

    $ curl -O 

    This command downloads the source to a local file called git-credential-osxkeychain.  If you don't have curl installed you can use this link

  3. Move the file to the /usr/local/bin directory.

    $ sudo mv git-credential-osxkeychain /usr/local/bin/
  4. Make the file an executable:

    $ chmod u+x /usr/local/bin/git-credential-osxkeychain 
  5. Configure git to use the helper.

    $ git config --global credential.helper osxkeychain
    # Set git to use the osxkeychain credential helper

Step 3. Install Mercurial

You can use Mercurial from the command line or you can use one of several GUI-based tools such as Sourcetree.  These instructions assume you are using Mercurial from the command-line.

  1. Make sure you have root access (sudo) on the system where you want to install Mercurial.
  2. Download the Mercurial installer from its official website.  
    The installer is contained in  ZIP file.
  3. Double-click the ZIP file to expand it.
  4. Double-click the MPKG file to run the installer.
  5. Follow the prompts to complete the installation.
  6. Open a terminal window.
  7. Verify the installation was successful by typing the following at the command line.

    $ hg --version

    Hg is the chemical symbol for Mercury and hg is the command for mercurial. 

  8. Determine if you already have a ~/.hgrc file in your environment by entering the following at the command line:

    ls ~/.hgrc

    If for some reason, you don't have the .hgrc file, you should create one yourself using the touch command:

    touch ~/.hgrc

    Files that start with a . (period) are hidden files in Mac OSX. By default, the Finder does not show these files. To reveal hidden files, enter the following command into the terminal:

    defaults write AppleShowAllFiles YES

    To hide them files once again, enter the following command:

    defaults write AppleShowAllFiles NO
  9. Open the Mercurial configuration file ~/.hgrc  using your favorite editor.
  10. Add a username value to the configuration.

    When you are done, the ~/.hgrc file includes the following lines with your own username and email address:

    # Name data to appear in commits
    username = Mary Anthony <>

    This is default value Mercurial uses, you can also set this for specific repositories (you'll learn more about this later).

  11. Save and close the .hgrc file.


The next step is to Create an Account and a Git Repo 

Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport