Jean-Luc Thiffeault's Homepage

BitBucket and Mercurial

BitBucket is a cloud-based repository for project management. It is very convenient for collaborating: it allows several people to work on the same project together. Unlike Dropbox, users choose when to "push" their changes to the server, so code or documents don't get stuck in an intermediate state. Two users can even make changes to the same file at the same time, and the version manager will merge the changes. Finally, users write log messages to go with their changes, which explain to their collaborators what the changes were.

There are many version-control programs (RCS, CVS, Subversion, Bazaar, Git,...). I use Mercurial for my private BitBucket projects. Git with GitHub is by now much more popular, but I find Git's interface overly complicated for simple version control involving a few users. In addition, GitHub charges a high fee for private projects. I do use Git/GitHub for open-source projects such as braidlab.

Setting up BitBucket and Mercurial (Linux and Mac)

  1. Sign up for a free account. Use your academic e-mail address to get a better account type. You can add other e-mails afterwards.

  2. Download and install Mercurial on your computer. On Ubuntu and Debian Linux, this is as simple as
        sudo apt-get install mercurial

  3. Create a Secure Shell (SSH) key, by typing (in Linux or Mac):

        ssh-keygen
    Press enter to accept the default. (If asked to Overwrite, you already have a key and can answer no.) Then type a passphrase (twice), which is like a password except that spaces are permitted.

  4. Log in to BitBucket, and go to Manage Account (in top right drop-down menu), then SSH keys.

  5. Click Add Key, and paste the output of

        cat ~/.ssh/id_rsa.pub
    This should be a long string of nonsense, beginning with ssh-rsa.

  6. Repeat steps 2 to 5 for each computer you use. Alternatively, you can copy the files ~/.ssh/id_rsa and ~/.ssh/id_rsa.pub to the other computers. Then you don't have to add other keys to BitBucket.

The SSH key you uploaded will allow a secure connection between your computer and BitBucket. On a typical Linux setup, you will only need to type in your passphrase once per session.

Using Mercurial

  1. The very first thing to do, unless you don't plan on making changes or sharing them with others, is to set up your local Mercurial username. To do this, edit (or create if it doesn't exist) the file ~/.hgrc (on Windows, the configuration file is %USERPROFILE%\Mercurial.ini) and add the lines

        [ui]
        username = Eddie Shore <eshore@oldtimehockey.edu>
        editor = gedit  # On Mac, use editor = open -t -n -W
        [extensions]
        fetch =  # enable fetch extension
        color =  # nice color highlighting
        pager =  # automatically invoke pager
        shelve = # stow away changes temporarily
        record = # allow commit of separate hunks
    
    where you substitute your own name and e-mail address, and your preferred editor (set 'editor = open -t -n -W' to use TextEdit on OSX, for instance). Make sure to use an e-mail you registered with BitBucket. (Remember that you can add extra e-mails to BitBucket, so use whichever address you consider most "permanent", not necessarily your .edu one.) The last few lines enable some convenient extensions, such as fetch (see below).

  2. To get a list of basic Mercurial commands type

        hg
    by itself. A more complete list is returned by
        hg help
    To get help on a specific command, type
        hg help thecommand

  3. To get a local copy (a clone) of a Mercurial project (also called repository) such as flipper, type

        hg clone ssh://hg@bitbucket.org/Mark_Bell/flipper
    flipper is publicly available, so no password is needed. For private projects, if you have access to the project, you will be prompted for the passphrase associated with the key you created above. You only need to enter this passphrase once per session.

    Projects hosted as Git repositories (another version control program like Mercurial) can easily by handled by Mercurial using the hg-git plugin. To enable hg-git, add these lines to the [extensions] section of your .hgrc configuration file (see above):

        [extensions]
        hgext.bookmarks =
        hggit =
    
    You can then clone a project such as braidlab with
        hg clone git+ssh://git@github.com/jeanluct/braidlab.git

    By default, the clone command creates a subdirectory braidlab in the directory where you ran the command, but you can specify an optional target path.

  4. Now you have the entire history of the project available, but by default you will see the latest version. You can edit the files and make changes as usual. If you want to add a new file or directory, just create it as you normally would, and then explicitly tell Mercurial about it with

        hg add new_file_or_dir

    Note that new additions don't take effect until you commit them, as described next.

  5. To "commit" local changes once you're satisfied with them, use

        hg commit
    An editor will pop up for you to enter a log comment (save and exit when done). If the log comment is short, you can specify it directly on the command line:
        hg commit -m"Added file new_file_or_dir, which does stuff."
    Write something descriptive (if you use several lines, the first should be a summary and stand on its own), and a new revision is created (also called a changeset). Revisions can consist of several additions, deletions, and/or modifications of files in the project.

  6. Often you'll notice that you committed a file you didn't mean to, or you made a mistake in the commit message. Issuing

        hg rollback
    will undo the previous commit (unless it was pushed to the server already, see next item).

  7. Unlike Subversion and many other version control systems, in Mercurial commits are not uploaded to the server automatically. This encourages 'small commits' with well-defined changes. When you are ready you can upload all your commits by issuing

        hg push

    To make sure you have the latest version when you return to a project that you previously cloned, execute the "fetch" command:

        hg fetch
    from within the local project directory. To use it, the fetch extension needs to be enabled in your .hgrc file, as done in item 1 above. See the next item for some details about fetch.

  8. Fetch is a very convenient "extension" that was enabled in item 1 above. It automates the three standard steps for bringing your repository up to date with the BitBucket server. Here is how to do the same thing, but without using fetch.

    First we "pull" changes from the BitBucket server, which is equivalent to the command

        hg pull --update
    The --update flag (which can be abbreviated to -u) tells Mercurial to also update your working copy to the latest revision.

    If someone else pushed changes, you might get a message when you pull that a merge is needed. Most of the time, simply issuing

        hg merge
    will merge your current state with the changes. Note that you then have to commit again:
        hg commit -m"Merged changes."
    The reason for this extra commit is that the merge might require some tweaking to make sure everything works (code is not broken, etc.), so Mercurial adds this extra step to allow the user to intervene before accepting the merge.

    The fetch extension does the 'hg pull -u; hg merge; hg commit' sequence all in one go, but it will not proceed if it finds changes that cannot be merged automatically, such as when two changes occur in the same line of a file. If such conflicts occur, you will need to read up on merging, or call someone to the rescue.

  9. Other useful Mercurial commands include

        hg status
    which gives "status report" of the current state of your local files (M = Modified, A = Added, R = Removed, ? = not under version control), and
        hg diff
    or
        hg diff paper.tex
    which lists the differences between local file and the original file. It is also useful to view the change history (or log) for a file or directory:
        hg log paper.tex
    Finally, to remove a file or directory run
        hg rm paper.tex
    which deletes the file, but will also delete for you collaborators when they pull changes from the server. Note that removals should be explained in the commit log message (as should everything else!).

Some tips:

Advanced Features

For more information see the Mercurial Book.