.. !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``.