Skip to end of metadata
Go to start of metadata

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. Bitbucket supports Git 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.

Linux or Mac User?

Mac users see this page.
Linux users see this page.

Step 1. Install Git for Windows

Here's how to install Git on your Windows machine:

  1. Download the Git for Windows installer package.
    You can either Run the installer directly from your browser's File Download dialog or you can Save the file to a folder on your computer.
  2. When you've successfully started the installer, you should see the Git Setup wizard screen. Follow the Next and Finish prompts to complete the installation.

    The system opens the release notes. You might want to skim them.
  3. Open Git Bash.vbs from the Git folder of the Programs directory to open a command window.

    Using the Git Bash window, you can enter the git command lines that appear in the Bitbucket documentation.

  4. Configure your username using the following command, replacing Emma's name with your own. Copy and paste the code after the $ and press enter.

    $ git config --global "Emma Paris"
  5. Configure your email address using the following command, replacing Emma's email address with your own.

    $ git config --global ""

Step 2. (Optional) Install the Git credential helper on Windows 7 or 8

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-winstore 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, do the following in your Windows 7 or 8 (.NET4.0 required) environment:

  1. Download the git-credential-winstore application.
  2. Make a note of where you downloaded the application.
  3. Start the Git Bash shell.
  4. In the shell, change directory to the directory with the git-credential-winstore download.
  5. Install the credential helper by entering the following at the command line.

    ./git-credential-winstore -i /bin/git

    The command updates your global Git configuration.

Step 3. Install Mercurial

TortoiseHg 2.2.1 is the Microsoft Windows version of Mercurial. 

  1. Download the all-in-one installer (MSI version) from the Bitbucket repository (shameless promotion (wink)) .

    If you downloaded the file to a folder on your local machine, you can also click the downloaded file's icon to run the installer. When you've successfully started the installer, you should see the TortoiseHg Setup wizard screen:

    The version shown on your screen may be different than the one shown here of course. That is ok as long as you are installing a TortoiseHg that supports Mercurial version 1.7 or later.

  2. Press Next to move to the next page of the wizard.
    The setup displays the license agreement.

  3. Press Next to accept the license agreement and continue.
    For this setup, use all the default setup values recommended by installer.

  4. To accept all the defaults, press Next on each page of the dialog that comes after the license agreement until the wizards prompts you to install.

  5. Press Install to install the software.
  6. Press Finish on the final page of the dialog to complete the installation.
    You may need to restart your system for the installation to take effect.

Do the following to configure your global default username and email:

  1. Right-click in your Desktop to open the context menu.
    The system displays the right hand context menu:
  2. Click the Hg Workbench item.
    The system opens the TortoiseHg Workbench application.

  3. Choose File > Settings to open the TortoiseHg Settings dialog.
  4. Locate the Commit section on the left hand side and click it.
  5. Fill in the Username value using the following format:
    firstname lastname<email>

    When done the dialog looks similar to this:
  6. Press OK to save your changes.

Step 4. Install PuTTYgen and configure PuTTY

PuTTYgen is a free RSA and DSA key generation tool. You'll learn more about RSA, DSA, and key generation later in this tutorial. If you don't have PuTTYgen or PuTTY installed, follow the instructions below to download, install, and configure the tools:

  1. Download the proper version of the utilities for your system – each one is a single executable file. 
  2. Move the puttygen.exe executable to the C:\Program Files\TortoiseHg folder.
  3. Start Putty.
    The PuTTy Configuration dialog displays. Use this dialog to configure your PuTTy sessions. 
  4. Under the Session node, select Default Settings and press Load.
    This allows you to edit the Default Settings session configuration. 
  5. Under the Connection node, click SSH.
     The Options controlling SSH connections display.
  6. Check Enable compression.
    This option can improve performance of a low-band connection. 
  7. Click the Session node, select Default Settings and press Save.
  8. Click the Close button (red x).

Next Steps

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


  1. Anonymous

    echt ein super tutorial, welches mal schritt für schritt alles erklärt!!!


    Vielen Dank!

  2. Anonymous

    What he above me wrote, but then in English (smile)

    1. Danke and you as well in English!

      1. Anonymous

        Bitte = You're Welcome


  3. I am feeling happy over my decision of switching from github. This tutorial is very easy to follow.

  4. Please update the tutorial contents and add TortoiseGit also.


    1. Muhammad,

      I'll bring up your request to our project manager. I'm not full time on the bitbucket documentation so we have to balance enhancement requests against my other responsibilities.



  5. Anonymous

    There is also TortoiseGIT that makes working with GIT bit easier, you might want to have a look at that and add it to documentation, however TortoiseHG steps probably work for that one too.

    1. Good reference.  Msygit is used in this tutorial because I can get "double-work" out of the Git examples — they work in both a Linux env and a GitBash on Windows env.  

  6. Anonymous

    How about using Tortoise SVN doesn't it work ?


    1. That wouldn't surprise me. I think TortoiseSVN is only intended to work with SVN.  I could be wrong there.  Why do you think it should work with Git or Mercurial as well?

  7. Anonymous

    Mary, I understand the desire to clean up the comments on this page, however the negative connotations of editing is not a good p.r. strategy.  If you'll notice, this is why Amazon, eBay and others don't remove comments, even if they are negative.  People tend to ignore such rhetoric when they see it, and move on.  Also, the Google and Bing search engines like the continual posts and updates and rank you higher because they see updated relevant information.

    1. You know, I hadn't considered that view point.  I remove comments regularly. Typically, I remove them because 1) I've incorporated the information or 2)  answered a question or 3) they have aged out. Rarely, do people make rude comments but those I do remove and spam of course.

      Are Amazon and eBay good examples of comparable use cases? Don't know. These pages are documentation. Their goal is to get readers information quickly and accurately.  The majority of feedback the company gets on comments is that long comments threads are distracting. And, in some cases, misleading.  Readers typically ask us to remove them. 

      There is a push within the Company to turn comment off all together on documentation. I don't agree with that position.  Sometimes, a page is wrong and a customer has a comment that can help others until I get around to incorporating.  Why is there a push to turn them off?  The long comment threads are often cited as a reason. (For myself, I want to do a usability test on the whole issue.)  

      As for the positive comments, I tend to leave those behind for selfish reasons. They make me personally happy. (smile) There really aren't that many of them.  To be fair though, I can remove them on a regular basis as well.

  8. Anonymous

    Would it be possible to add a tutorial for Mac OS X. I had a hard time finding how to install git and the rest. I'm not even sure if everything I install will be really useful at this point. A little help would be welcome

  9. Hi,

    I was using the tutorials fine as a first time user until I tried to set up the SSH services later in the tutorials. I just now tried setting up bitbucket on another computer and am on this first step of the tutorials again. I have a question which might explain why Im having issues setting up an SSH service. When installing Git and Mercurial I'm wondering how important my Windows system type is (X86 or X64). My System type is Windows X64 which maybe be an issue in this tutorial? The GIT installer linked here is a X86 version for windows that installs in my C:/Program Files(x86) and the Mercurial basic installation sets up in C:/Program files. As these two programs are in seperate folders in the basic setup, will there be issues in them communicating in an SSH service. Additionally When trying to install PuTTYgen via this tutorial the linking page lists only X86 versions of Puttygen for windows, don't I need a 64x version for my X64 system? Is there a PuTTYgen X64 version?

    Thanks for assistance with my questions.

  10. Anonymous

    Okay, this is strange. The .gitconfig file is refusing to display its filename. I see the icon, but there's no text in any view of the folder (Win7 x64). Is this a known bug (google doesn't return any results)? Git doesn't seem to have any trouble accessing it, but seeing a file with no name is kinda freaking me out.

    1. Hmm, this is hard for me to visualize.  Can you provide a screen capture showing what you are seeing?

  11. Anonymous

    I figured it out–turning off "hide known file extensions" fixed it. Apparently, Windows saw the ".", decided gitconfig was a known "file extension," and hid it.

  12. Anonymous

    What does DVCS mean? I've got Mercurial set up, is that a DVCS?

    1. DVCS is  distributed version control system.  It is defined on the first page of the tutorial.

  13. Dear Mary,

    I have a question about:

    Step 1. Install Git for Windows

    8. Configure your username using the following command:

    git config --global "FIRST_NAME LAST_NAME"


    9. Configure your email address using the following command:

    git config --global ""

    How many users can I have on the same computer?

    If I can only have one user on a computer how can I delete a user that is stored in the git bash interface?

    1. Cameron,

      Git has the concept of system, global, and repository specific settings for things like

      • system – every user on a machine and all their repositories
      • global - all repositories within a user's environment
      • repo - actions within that repo

      The first part of this page is a good intro to these concepts:

      So, if you have multiple user.names you commit under, you would configure the one you use most often as your global user. For repositories where you want to be known as a different user, you would configure that username in the repository's .git/config file.  I like to edit the configuration files myself but you can just run the git config command also.

      Hope this helps. 



  14. Anonymous

    I haven't read all of the tutorial yet, but the clear, complete writing of the first few pages has me convinced to get a Bitbucket account and try it out. I signed up with a competitor yesterday but found the documentation lacking and the process, from what I observed, was too heavy. Thanks for providing documentation that makes Bitbucket readily accessible to everyone.  

    One little nitpick:

    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 one or both of these tools installed, skip the instructions and go to the next step in the tutorial.


    The underlined parts sort of contradict each other.  You say we need both to complete the tutorial, but then say we can skip installation if we have either one.  It makes me think that we could work through the tutorial using either Git or Mercurial, but it leaves me uncertain.  Not a big deal, since both are free and downloading them isn't a problem.  It just made me wonder.

    1. Hi,  apologies for the slow reply.  A very thoughtful comment and you make a good point. I'll correct that.  Thank you for pointing it out.

  15. Thanks for the tutorial!

    I'm trying to get set up using only git, not Mercurial. In Step 4, can I place puttygen.exe somewhere other than the Mercurial folder?

    1. Sure, you can drop it wherever is convenient.

      1. That was quick. Thanks!

        1. Anonymous

          That's what she said.

          1. ok I was not expecting that. Not on this forum. rofl rofl 

  16. Anonymous

    Hi all accounts in our team are not accessible using git from windows From the morning. We saw that Bitbucket team did some change in SSH-key using, it cannot been changed from now. Is it possible the reason of the permission reject?

    1. My suggestion would be you first try, Troubleshoot SSH Issues. If that page does not help you find the issue, please file a report with


  17. Anonymous

    Hi, I'm sure this is a noob question, but on step 4.3 says start puTTy, where can I find that?  Are you referring to puTTYgen.exe?

    Thank you

    1. Yes.  You should also be able to Start it from the Windows Start menu.

      1. Anonymous

        This confused me as well.  The step-by-step instructions are missing something, but I don't know what exactly.

        They imply that you should only download the puttygen.exe file and put it in the TortoiseHg folder.  But doing so does not add PuTTy (putty.exe) to the system as that is a different exe.  Maybe you are assuming people will download the full installer that installs all the putty utils.

        I wasn't sure what I was supposed to do exactly, so I also downloaded the putty.exe file and put that in the TortoiseHg directory as well and ran it from there.  I guess I'll find out later on if that works or not..

        1. Anonymous

          Did this work? I also started "puttygen.exe" but it looks nothing like the tutorial. I'm on Windows 8.1.

        2. Anonymous

          I tried installing the full putty tools. If I then start just "putty", I see the configuration just as you say. When I get to the page on using Hg for myquotefork, I'm getting a 404 error. I'm not sure if they are related, but I think I'm going to stop on the Hg stuff and just do the git example. Can you double check both this and the status of the quote site? It looks like the site is blank. I'm confused. :\

  18. Anonymous

    Are Git and Mercurial independent? Meaning, if I just want to use Git, can I skip Mercurial (Steps 3 and 4)? Thank you!

    1. Yes, Git and Mercurial are independent of each other and you can complete the majority of tasks in the tutorial using Git alone.


  19. Anonymous

    I am having trouble in installing credential winstore. git bash giving an error. Please refer this thread I have created

  20. Anonymous

    your description of puttygen and what the program actually looks like don't match. There is no Putty Configuration. There is no Session or Connection node.  There is a Key section, an Actions section and a Parameters section. The File, Key and Conversions menus similarly have none of the "nodes" mentioned in the tutorial.

  21. Anonymous

    Same as above poster, I have downloaded puttygen.exe, moved it to the TortoiseHg directory and run the executable, and the window appears nothing like the one you have described in the tutorial. Should I actually be running a different putty executable than the puttygen.exe in order to access the configuration screen you describe?

    1. Thank you both! I will take the time tonight to go back through this process and update the tutorial accordingly or update this comment with the results.

      1. Anonymous

        I'm also having the same issue with the puttygen.exe - when I double-click to execute it after moving the file I do not get a configuration screen just a generate key screen.  Was there ever a solution to this?

  22. Anonymous

    I will setup thats all, and WTF is this? i can't do nothing whith that! 

  23. What do I need to install Mercurial for? Do I still need it if I am going to use command line / git bash for work or TortoiseGit?

  24. Below link to download GIT redirect to 403 page.

    Download the Git for Windows installer package.

    Please see

    1. Good day Naveen,

      Thanks for pointing this out! I've changed the download link to point directly to the download page.

      Have an exceptional day,



      1. Thanks a lot Dan!!!!!

  25. hi there. it seems I did everything correctly but i have "fatal authentication failed for". it's already 4 hours I can't figure out the problem

    1. Hello Albert,

      Are you trying to set up Git or Mercurial?

      When do you get the error? Is it just trying to push or pull from Bitbucket?

      Have you been unable to connect at all? Meaning have you been able to clone a repository or have you not been able to connect at all?