To start using Bitbucket, go to and create an account. The communication channel with Bitbucket repositories is either through SSH or HTTPS. To use SSH, you must upload your SSH key, typically the contents of the file or in the .ssh subdirectory of your home directory. Go to the page for your account, choose SSH keys, and upload one of these files. The essence of the SSH keys is that they allow you to communicate with Bitbucket without using a password, which is very convenient.

There are links to extensive help pages if you do not have such keys or if you are unfamiliar with SSH. Follow these steps on Mac or Linux machines to generate keys: 1) check that you have ssh installed; 2) create a .ssh directory in your home directory; and 3) run ssh-keygen in the .ssh directory (you are prompted for a passphrase - just write something). On Windows one applies the PuTTY and the TortoiseHG programs to generate and register keys, see the help pages on Bitbucket. Once the keys are generated, you can continue using them on any computer.

Creating a new project

Click at Repositories and at Create repository. You can now

  • fill in the name of the project, here my-project,
  • decide whether the project is private or public (the number of private repos is unlimited for yourself, but you have to pay to invite more than five users in total to share your private repos unless you are certified to be a student or work at an academic institution),
  • choose between the Git or Mercurial version control system (here we assume you run Git),
  • click whether you want issue tracking for reporting errors, suggesting improvements, etc.,
  • click whether you want a wiki page associated with the project,
  • fill in a brief description,
  • click on Create repository.

While doing this you may also want to have the Bitbucket 101 guide available.

It is now time to clone (copy) the project to your laptop. Go to the project page (you are automatically brought to the project page when creating a new project). Find the Clone button, click on it, choose SSH, copy the clone line and run this command in a terminal:

Terminal> git clone

You must replace user with your own username at Bitbucket and my-project by the real project name.

The first time you do the clone command you may be prompted by cryptic Unix output ending with “Are you sure you want to continue connecting (yes/no)?”. Just answer yes.

The next step is to collect files and directories that should make up the project and put them in the my-project directory. Standing in the my-project directory, the following Git command is used to add all files in the current directory tree, except those having file types listed in .gitignore:

Terminal> git add .

Thereafter, the changes to the repository (here adding of files) must committed (registered):

Terminal> git commit -am 'Initial import of files.'

The text following the -am option is a required description of the changes that have taken place. This description does not matter much for this initial import of files into the repository, but is of importance for future commit commands so that you can easily track the history of your project files and inform others (and yourself) what you have done with the files.

The final step is to push the local changes to the master repo at Bitbucket:

Terminal> git push -u origin master

You must be connected to the Internet for the push command to work since it sends file information to the site.

Further work with the files must always follow the pull, edit, commit, and push steps explained in the section Using Git for Git.


There is a button Send invitation on the project home page where you can invite other Bitbucket users to have push (write) access to your repo. Many prefer to be notified in email when changes are pushed to the repo: click the settings wheel to the right, choose Services, then Email, and fill in the email addresses that are to receive notifications on updates. Under Access management you can fill in the Bitbucket names of users who are have pull (read) or push (write) access to the repo.

User web pages

Bitbucket can host web pages associated with a Bitbucket account, but does not yet offer web pages as part of a project. Say your account/username is user. Make a new repository on Bitbucket called Clone it, fill it with a file, and push back, e.g.,

Terminal> git clone
Terminal> cd
Terminal> echo "Welcome to my web pages!" > test.html
Terminal> git add test.html
Terminal> git commit -am 'First web page'
Terminal> git push origin master

You can now load the URL into a web browser and view the page. By creating various subdirectories you can host web pages for a series of projects in this repo.

Linking to Bitbucket files

Unfortunately, the default URL shown in your browser to a file in a Bitbucket repo contains information about the version of the file. For example, a file v1.c under Git might appear with the URL

The string 5fb228107044, called commit hash, is connected to the version of this file and will change when the file is updated. Such varying URLs are useless when you to link to the file in documents. To make a stable link to the latest version of a file (in a public repo), replace the commit hash by master and remove the final ?at=master:

Other endings of the URL with commit hash, e.g., ?at=default, requires the hash to be replaced by default.