Bitbucket

Today I decided to start my blog at WordPress. I choose Bitbucket as my first theme… and hope it won’t be the last.

So what is Bitbucket?

Bitbucket is a code hosting site, for the popular Mercurial version control system. With Mercurial, your data is distributed by definition, but you still need a place to share it, and keep track of your development.

Bitbucket is that. It provides a fully featured environment for managing development, including a wiki (naturally backed by Mercurial, you can clone it!), a powerful issue tracker, and easy collaboration with others.

Simply put, it takes the pain out of sharing code, and lets you focus on what you do best: Code.

What do I get?

• HTTP push/pull support
• SSH push/pull support (with public key authentication)
• Integrated flexible issue tracker
• Per-repository wikis (backed by hg repositories)
• Plenty of “services” for repositories, automatic issue resolving, web hooks, etc.
• Email support (for both paid and free plans)
• CNAME support, so you can keep the code on your own domain
• Collaborate with other users easily
• Source view with highlighting for many languages
• Forks and Mercurial Queue (MQ) integration
• A bunch of social aspects
• RSS/Atom feeds for everything
• Host static files on our CDN (Content Delivery Network)

What’s Mercurial then?

Mercurial is a distributed version control system, or DVCS for short. It is in the ranks of Git and Bazaar, leading a new paradigm of working with version control.

If you have been using other version control systems like CVS or SVN, you should feel right at home, as Mercurial’s command set is very similar.

The main difference between a traditional version control system and a distributed one is that the distributed system does not rely on one central server. Every person with a repository also has the full history of changes. Each repository is independent.

In Subversion, for example, each developer checks out a copy from the main server, works on changes, and commits them back in. In case of conflicting changes made by other developers, you will be notified and asked to merge the changes. In a DVCS world, this is different, as commits are local, and you can commit several dozens of changes locally without ever communicating with anyone else.

Getting started with Bitbucket

Be sure to install TortoiseHG in your machine before go any further. Yor can download it from http://bitbucket.org/tortoisehg/stable/. Installation is pretty straighforward, so I won’t discuss it here. After that you must create an account with Bitbucket at http://bitbucket.org/. Log in and we are ready to continue.

Starting a new project or importing your current project into Bitbucket is easy! If you haven’t already, you can create a fresh repository on the “Create repository” page, which is also accessible from your Bitbucket personal home page.

We will assume that you have created a new repository named testrepo and begin from scratch. If you already have a code base you want to import, skip ahead to the section “Importing existing files”.

The first thing you should do is clone the repository from us. This gets you a local copy of the entire repository, including all changes, but that won’t matter much since the repository you have just created is empty.

$ hg clone http://bitbucket.org/jespern/testrepo
destination directory: testrepo
no changes found
updating working directory
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
   

You now have an exact copy of what we had on our end. This means that you are ready to start work!

Lets add a few files:

$ cd testrepo
$ echo 'Hey this is a file I am about to add' > README
$ echo 'This is some other file.' > textfile.txt
$ ls
README    textfile.txt
$ hg add README textfile.txt
$ hg commit -m "Adding initial README file, as well as a file with text in it"
   

OK, hg is now tracking both README and textfile.txt, and has recorded their changes. Here comes the fun part, let’s publish it:

$ hg push
pushing to http://bitbucket.org/jespern/testrepo
searching for changes
http authorization required
realm: Bitbucket.org HTTP
user: <your username>
password: <your password>
adding changesets
adding manifests
adding file changes
added 1 changesets with 2 changes to 2 files
   

…and our changes are published. We comitted 1 changeset, which held 2 changes to 2 files. Makes sense? Great!

Importing existing files

Chances are you are either coming from a different version control system such as Subversion or CVS, and you want to get started using Mercurial instead. Luckily, you can push anything into an empty repository. This allows you to easily move any number of files into your new repository at Bitbucket.

Let’s say I have a project in ~/Work/Blonk, and I want to add it to Bitbucket. The first thing to do is create a new empty repository via the “Create repository” page. Again, we will assume that this repository is named blonk and is to be found on http://bitbucket.org/jespern/blonk.

First, we will make a local copy, by cloning it:

$ hg clone http://bitbucket.org/jespern/blonk
destination directory: blonk
no changes found
updating working directory
0 files updated, 0 files merged, 0 files removed, 0 files unresolved
   

Now let’s enter the directory, and copy all of our previous work in:

$ cd blonk
$ cp -R ~/Work/Blonk/* .
   

Now all that remains is to add and commit the files:

$ hg add
$ hg ci -m "Initial import of the old Blonk files"
   

And we can go ahead and push:

$ hg push
pushing to http://bitbucket.org/jespern/blonk
searching for changes
http authorization required
realm: Bitbucket.org HTTP
user: <your username>
password: <your password>
adding changesets
adding manifests
adding file changes
added 1 changesets with 162 changes to 162 files
   

We’re done. You may now browse to the repository online and see your files appear.

Continuing on from here

You now know how to create a new repository, and either work with it from scratch, or import pre-existing files. Of course, you are going to want to make changes to those files now.

The workflow remains the same:

• To add files to the repository, you hg add
• To commit changes, you hg commit
• To publish your changes, you hg push

Have fun!