Skip to end of metadata
Go to start of metadata

Now, you get to use Bitbucket! On this page you'll create an account on Bitbucket. Once you have an account, you can create a repository. Here are some quick facts about accounts, repositories, and projects:

  • both the username and email on an account must be unique
  • each repository belongs to an account (sometimes called a username or user for short)
  • the person who created the account is the repository owner
  • the repository owner is the only person who can delete the repository
  • a user (an account) can have an unlimited number of public and private repositories
  • a code project can consist of multiple repositories across multiple accounts but can also be a single repository from a single account

Even if you only intend to work with other people's projects, knowing how to create a repository is useful. Creating a repository is free so there is no reason not to do it.

Who needs an account?

Depending on what you want to do with Bitbucket, you don't even need to create an account. You need an account if you are:

  • a new Bitbucket user working through the Bitbucket 101
  • a developer who is working on a project whose code happens to be in Bitbucket
  • a project owner/leader who wants to share a Bitbucket project (repository) with others
  • a developer who wants to contribute to a repository in Bitbucket

Step 1. Create a Bitbucket account

If you already have an account, skip this section and go to the next. You can create an account with the standard sign up or you can create one through OpenID (using an existing Google or Yahoo account for example). Regardless of which sign on method you use, you must supply the following fields:

FieldAbout what you are supplying

Up to a 30 character username. You can use letters, numbers, and underscores in your username. Your username must be unique across the entire Bitbucket site.

Bitbucket appends this username to the URL for all the repositories you create. For example, the username atlassian_tutorial has a corresponding Bitbucket URL of

Email addressAn email address that is unique across the entire Bitbucket site. The system sends you a confirmation email.
PasswordA combination of up to 128 characters. If you are using OpenId the system uses that password. You are responsible for ensuring that your account password is sufficiently complex to meet your personal security standards.

To sign up for a Bitbucket account do the following:

  1. Open in your browser.
  2. Complete the fields in the sign up form.
  3. Click Sign up.

You can also sign up using your Google account information by clicking, Sign up with your Google account.

When you are done signing in, Bitbucket places you in the Dashboard of your account. Take a second and look around at the user interface. Across the top of each Bitbucket page is a series of options that let you navigate around Bitbucket.

Try displaying the Bitbucket keyboard shortcuts by pressing ? (question mark) on your keyboard.

To use most of the keyboard shortcuts your cursor must not be active. So you cannot be typing a comment, edit or have your cursor in a place where you would enter information.


Step 2. Create a Git repository (repo)

The next step is to create a repository. Initially, the repository you create is going to be empty without any code in it. Do the following to create your repository:

  1. Log into Bitbucket (
    The system displays your account Dashboard which should be empty if you just created an account.

  2. Click the Create button at the top of the page and select Create repository from the drop-down menu.
    The system displays the Create a new repository page. Take some time to review the dialog's contents. With the exception of the Repository type, everything you enter on this page you can later change.
  3. Enter bb101repo for the Name field.
    Bitbucket uses this Name in the URL for your repository. For example, the username atlassian_tutorial has a repository name jira-applinks, the full URL for that repository is You can use the URL to quickly navigate to a repository overview.
  4. Enter a short Description.
  5. For Access level, leave the This is a private repository box checked.
    A private repository is only visible to you and those you give access to (more about this later). If this box is unchecked, everyone can see your repository.
  6. Check Git for the repository type.
    You can't change the repository type once you pick one. For this tutorial, we create a Git repository first. Later we will work with a Mecurial repository.
  7. For Project management, check both the Issue tracking and Wiki checkbox.
  8. Set the Language field to HTML/CSS.
  9. Click Create repository.
    Bitbucket creates your repository and displays the repository Overview page.

Step 3. Explore your new  repository

Take some time to explore the repository you have just created. You should be on the repository's Overview page:

Across the top of each repository is a menu bar (1) that you use to navigate around to your repository's pages. Click items on the bar to see what is behind each one. An actions area (2) where you can clone, branch, create a pull request, and other repository actions. The repository administrator settings (3) to open the admin page. The (4) section contains a get started workflow for a new repository, which is replaced with the activity feed once you get working.

You can also navigate using the repository shortcuts. To view the shortcuts available:

  1. Click somewhere in the Bitbucket browser window to gain focus.
  2. Press the ? (question mark) on your keyboard.
    The shortcuts list displays.

Try clicking the Commits option on the menu bar. You find there are No commits recorded yet (during your repository exploration you probably saw this message as well). You have no commits because you have not created any content for your repository. Your repository is private and you have not invited anyone to the repository. So, the only person who can create or edit the repository's content right now is you, the repository owner.

Step 4. Confirm your email address

When you create an account, Bitbucket sends an email to you to confirm your email. Confirming your email allows Bitbucket to automatically match your user account to your future source code commits. Do the following:

  1. Open your email client (Gmail, Outlook etc).
  2. Find the email confirmation from Bitbucket.
  3. Open it.
  4. Confirm the address.


Now that you've created your first repository and explored it a bit, you are ready to add content to it.


  1. Anonymous

    Is it really needed to have a four step process describing how to confirm your email address? 

    1. An interesting question. I design documentation for novices as they need more help than experts. Also, of course, you might be a native English speaker not all of our users are. We do get support issues on lost confirmation email. Finally, consider over 9,556 people have visited this page.  You are the first to comment on the number of steps. That isn't to say your comment is false/bad/whatever. It does imply that for those who found the length of the procedure irksome, only one took the time to comment. So, more than likely an outlier.


      1. Anonymous

        Mary Anthony [Administrative Account]


        You're 100% right.

        Personally, I admire your work and how you make it easy to understand for novices.

        Some people are inconsiderate, forget that they were once novices too, needed all the help they could get.

        Not everyone was born a coder or a computer techie.



      2. Anonymous

        Don't listen; your docs are great and proved useful every step of the way. It's easier for me to skip over something because it's trivial than for me to be staring blankly at the screen because you left something out!

      3. Anonymous

        Yup.  Probably more than necessary.  But I'd much rather have too much information than not enough.  Keep up the good work.

      4. You did really a good job, you are a serious writer and you deserve good comments! leave those guys who cannot understand people's work.

        1. I'm glad you like the docs Brian!  To be fair, your comment reminded me, I really should check with Support; It could be lost confirmation emails are no longer the issue it was in 2012.  

          1. Anonymous

            Actually I didn't get any confirmation email when creating my first repository! 

            1. You can actually get the system to resend the confirmation

      5. Anonymous

      6. Anonymous

        Experience is talking !!

  2. Anonymous

    Good tutorial!


  3. Anonymous

    I'm not a novice and didn't notice the four lines until I'd confirmed my email etc. but blimey, how nice to have full, helpful documentation rather than the short-cutting rubbish you normally find especially in the open-source community.  As a professional developer not in need of that help, I'm left with an impression of serious professionalism by such clarity.  Well done (smile)

    1. Wow. Thank you.  Made my day.

  4. manthony

    Really you are doing well. Four step email confirmation is not necessary but the beginner level can not be measured specially in such type of tutorials. So I like your detailed way. There is no under estimation. Bravo.....

    1. Muhammad thank you for that comment.  It is tricky to write one tutorial for such a diverse population as the bitbuckians.  Every comment helps me tweak — so I very much appreciate them. 

      1. Anonymous

        Full documentation is a good thing.  I already confirmed my email before reading this tutorial, but I still respect, and appreciate the full documentation.

  5. Anonymous

    This is only instructions to create a git repo. How do you create a repo using mercurial?

    1. You can create a Mercurial repo at any time by selecting Mercurial from the Create new repository dialog. As you progress through the tutorial, you will fork a Mercurial repo.  

  6. Anonymous

    Great tutorial, i like it (where is the like button..., just kidding). There is a minor typo in Step 2, point 3: "has arepository" should be "has a repository".

    1. Hey thanks on both counts! Typo wasfixed — just kidding was fixed. ;-D

  7. Anonymous

    You should be given high praise for taking the large amount of time that I am sure this tutorial took to create to make an excellent tutorial. I truly believe that a more detailed tutorial is of greater value than a quick brief tutorial....Advanced users can quickly skip stuff they know but beginners do not have that option if the information is not there...Some developers have to remember that not everyone using this service would be a git expert or even a command line expert. Similar to what an earlier commenter experienced, I too have come across many open source tools where the documentation is very brief and assumes everyone is a command line expert or is on a Unix/Linux Mac OS/X system where the command line is called a command Windows it is called the Command prompt...Anyways I have found this tutorial excellent...Thank you for making it...Do not listen to the cranky nerds, keep it detailed for the beginners.

    1. Thank you for taking the time to write this.  You pretty much encapsulated my own writing philosophy. The goal is to write to the novice and not hinder the experienced folks. Course, now I have to go convince my team that I did not pay a friend to write a comment for me...or maybe I wrote it in my sleep. (big grin) Anyway, thank you very much I appreciated hearing this.

  8. Anonymous

    thank you for the tutorial. I came from svn and I was having a lot of difficult to use git. but now everthing is clear.

    1. You are welcome — and welcome to Git!

  9. Anonymous

    Thanks for your efforts in writing/editing this Mary.  


    The only suggestion I've got would be a clearer picture of you.   (smile)

  10. Anonymous

    What impact does the language field have?

    1. None. It just is a way of providing information.

  11. Muchas gracias por tu detallada explicacion. Es muy util para novatos como yo. 

    Thank's a lot for your detailed tutorial. It is really helpful for novices like me.


  12. Great job, this tutorial is very helpful!

    Regards from Argentina

    1. Thank you Cesar from Argentina! Very cool.

  13. Anonymous

    Thank you very much (smile)

  14. Anonymous

    Thank you for your efforts in writing the tutorial. Very neat and detailed. 

  15. Anonymous

    Thanks for the tutorial, agree that the not-even-a-second it takes to scroll through four email confirmation steps is worth it.

  16. Anonymous

    It's easier to confirm your email address if you copy+paste the link into the same browser where you created your BitBucket account. If you signed up with your non-default browser, you'll have to login again when the link uses your default browser.

  17. Question: How can I already add the contents of an existing folder to git version control?

    Tutorial here covers the case of making a directory and then adding source contents to it. I have some source code in a folder that is path dependent and dont want to move it. 

    So - How can I just go into my folder and make it a repository?

    1. Neil, yes the tutorial is very specific because I'm trying to teach many folks the basics. Bitbucket actually provides online help for just your case. Right after you create a repo, the system dumps you into a blank repo with a help panel:

      You'd choose the second help and then the system displays the appropriate commands. In this case, they are:

      cd /path/to/my/repo
      git remote add origin ssh://
      git push -u origin --all  
  18. Anonymous

    I'm so impressed with how friendly your docs are. Great job for making it easy and understandable especially for beginners. Regards from the Philippines! (smile)

    1. Thank you always glad to help. And hello from California!

  19. I created a new repository and added a Group of users. Now when I go to the overview tab, I see the "Get started". When they go there, they see "No commits recorded yet. ". If I make one of them part of the Administrator group, that one can now see the "Get started". What am I missing?

    1. Well, at this point, someone with write permissions (you, the other admin, or a group member if that group has write) needs to push code to the repo. Just following the Get Started instructions. (Apparently,we only show those instructions to Admins and so I'll see about removing that restriction on the instructions.)

      1. Just to confirm that the user group mentionned was setup with "Write" access, but no "Admin" access. So it confirms that only Admin users sees the messages on how to upload code.

        1. Patrick thanks for the confirmation. That is exactly what I thought.

  20. Anonymous

    Excellent tutorial! 

    One suggestion: provide a path for those who will be using an existing repository instead of creating their own.

    1. Thank you for the complement! I will be taking the reigns of the tutorial from manthony and will look into your suggestion.

  21. +1 Excellent tutorial !!

    For someone like me that just need to get into Bitbucket and Git from scratch, this tutorial in a standalone weapon !! Thanks.

    1. Thank you for the lovely complement. I'm very grateful for the excellent work manthony has done and hope to continue that good work.

  22. Anonymous

    Great docs! In step 3 clicking in the browser window and pressing ? did not reveal any short cuts... I must be doing something wrong. Firefox browser with no special interface add-ons...

    1. Thank you! If you click on the page and then press the ? that should reveal the shortcut or 'hot key' list. I think it might be that it sounded like you click and press ?, but you click then press ?. Hope that helps.

    2. Yes. I had the same experience.

      I spent a few minutes focusing on various parts of the pages and pressing '?' in an attempt to get the Keyboard Shortcuts to show. To no avail. They did show up when I pressed '?' in these, Atlassian, docs pages.

      Later I discovered that there is a 'Keyboard shortcuts' setting in the Bitbucket > avatar > Manage Account section which toggles this feature on and off. It is OFF by default on new accounts. So, that is why it was not working. Turn that feature ON to see magical effects of pressing '?' in

      I think the line in Step 1, above, could be removed for clarity.
      i.e.: This is just confusing for fresh users: "Try displaying the Bitbucket Keyboard shortcuts by pressing ? (question mark) on your keyboard."

      And the lines, below that, in Step 3, could be changed



      You can also navigate using the repository shortcuts. To view the shortcuts available:

      1. Click somewhere in the Bitbucket browser window to gain focus.
      2. Press the ? (question mark) on your keyboard.
        The shortcuts list displays.





      You can also navigate using the repository shortcuts. To view the shortcuts available:

      1. Visit > avatar > Manage Account section and ensure Keyboard shortcuts setting is checked.
      2. Click Save Settings.
      3. Click somewhere in the Bitbucket browser window to gain focus.
      4. Press the ? (question mark) on your keyboard.
        The shortcuts list displays.


      Just sayin'.

      1. Thanks for taking the time to comment. I'll be making additional changes to clarify. 

        Happy coding,


  23. Anonymous

    100 likes (smile)

    1. Thank you! I like your 100 likes. (smile)

  24. Anonymous

    Hi there,

    whatever I try to do (clone, or upload) I always get the warning "fatal: could not read Password for  '': No such file or directory" , but I am totally unaware what I have done wrong, or where to set the password. Can you please give me a pointer on how to solve this?



    1. Hello David,

      I'm going to be updating this section of the tutorial later today as this problem seems to be a running theme. On your initial clone attempt, modify the script you copy from Bitbucket:

      From this: git clone

      To this: git clone

      Password security

      As a caveat to the above instruction. This will mean you have your password in your bash history. To clear the  password from your command line history do the following before closing the command line:

      1. Type bash at the command line. This will switch you to the bash command line.
      2. Type history from the bash command line.
      3. Locate the line number where your password was entered.
      4. Type history -d the line # from step 3 and press enter.
      5. Type history -w
      6. Type history and check your the line number. Your password should no longer be in the history.
      7. Type exit to return to your home directory command line.


      After this initial clone you should be prompted to enter your password for other operations.

      I hope this resolves the problem. I'll look into a more permanent fix.

      Thank you for taking the time to go trough our tutorial!

  25. Anonymous

    Very wonderful explanation.