.. !split .. _bitgit:bitbucket: Bitbucket ========= .. index:: Bitbucket To start using Bitbucket, go to ``bitbucket.org`` 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 ``id_rsa.pub`` or ``id_dsa.pub`` 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 (1) ----------------------------------- 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: .. code-block:: text Terminal> git clone git@bitbucket.org:user/my-project.git 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``: .. code-block:: text Terminal> git add . Thereafter, the changes to the repository (here adding of files) must *committed* (registered): .. code-block:: text 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: .. code-block:: text 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 ``bitbucket.org`` site. Further work with the files must always follow the pull, edit, commit, and push steps explained in the section :ref:`bitgit:git` for Git. Collaborating (1) ~~~~~~~~~~~~~~~~~~~~~~~~~~ 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. .. _bitgit:bitbucket:web: User web pages (1) --------------------------- 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 ``user.bitbucket.org``. Clone it, fill it with a file, and push back, e.g., .. code-block:: text Terminal> git clone git@bitbucket.org:user/user.bitbucket.org.git Terminal> cd user.bitbucket.org 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 ``http://user.bitbucket.org/test.html`` 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. .. _bitgit:bitbucket:URLs: 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 .. code-block:: text https://bitbucket.org/user/proj/src/5fb228107044/dir/v1.c?at=master 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``: .. code-block:: text https://bitbucket.org/user/proj/src/master/dir/v1.c Other endings of the URL with commit hash, e.g., ``?at=default``, requires the hash to be replaced by ``default``.