Introduction to Mercurial and Bitbucket

In my recent posts, I hosted source code in Bitbucket. Bitbucket is a free code decentralized version control system (DVCS) hosting site for Git and Mercurial. In comparison to GitHub, Bitbucket allows us to host unlimited private repository for free – GitHub not. In Bitbucket, we can also integrate with other great Atlassian products for managing our development with a hosted wiki and issue tracker. Because I will host my code there in future as well as moving slowly all available .zip code files from my site to Bitbucket, I would like to write a short instruction so that you know how to check out or download the code. However I won’t go into details how Mercurial works and how great the products of Atlassian are. The topic of this blog post is very limited only in source code download section, no commit and everything else.

1. Use case

If you follow my blog, you know that each of my post discusses only about one point of interest for programming, computer security or anything else I’m interested in. For programming category, I always try to make a simple application for illustrating how the concept looks like. The sample application is never an end-product, it’s only a demo. Sometimes I have to fix some bugs or extend the functions of sample code according to questions of readers. Such changes make the current source code different with the one in post and maybe make the reader confused. This problem can be easily solved with a code revision repository. By using a distributed version control system, we can check out a specific version of source code or easily follow which changes are applied between the versions.

There are many version control systems out there. There’s a good one, there’s a bad one. Maybe one prefers SVN, the other prefers TFS or GitHub or something else. I myself prefer Mercurial ( and Bitbucket offers a great free service for Mercurial. So I just use Bitbucket with Mercurial, not for any special reason. Moreover, as I said at the beginning, I won’t try to explain how Mercurial and Bitbucket work but I will focus only how you can check out the source code, you want from my repositories at Bitbucket.

Let’s take an example, in one of my posts Android – Show images from Flickr with ImageGridView, there is a question if it’s possible to extend the demo with 2 buttons for downloading and sharing over social network. I have extended the demo code for this question by adding 2 buttons. However this changes make the source code not as it was, like in my original post. Therefore I branched the original one into release 1.0 and I make a new branch for the changes called release 1.1. Now how can you get the version you want?

In next parts, I would like to show you 2 methods to download the correct source code. One directly from Bitbucket (for whom doesn’t use Mercurial) and one with Mercurial TortoiseHg (for whom doesn’t use Mercurial but want to try it). For whom already uses Mecurial, then just skip this post. Nothing interesting here ;).

2. Bitbucket

The source code of example with Flickr is hosted under this link

Android – Show images from Flickr with ImageGridView

When you browse to this link with browser, you’ll land on Bitbucket website with many options for navigating through the source code as well as cloning or forking. This repository was set for using with Mercurial so if you’re not familiar with Mercurial, maybe it’s pretty ‘difficult’ to clone the source code. However the good news is: You don’t have to. On the left menu in Bitbucket website, look for menu Downloads

Bitbucket Downloads section

On the right panel in Downloads section, you’ll get 3 tabs: Downloads, Tags and Branches.
Downloads : this download will give you the complete repository. The code you get is from the beginning until the last commit. But if you don’t use Mercurial, this download doesn’t mean to you because you can only see the code of the last commit.
Branches : this section will give you the ability to download the current source code from a specific branch. Again, if you don’t use Mercurial, this download doesn’t make sense too because what you see is only the code of last commit in that branch.
Tags: here is the correct section for you. In this section you’ll find the Tag I made after releasing each version. Files from this section are exact for each release version (not from last commit). For our example above, if you want to check out the version corresponding to the post, then take 1.0, if you want the version with 2 buttons, then take 1.1.

Tags section

3. TortoiseHg

In previous part, we learn how to download directly from Bitbucket website. If you haven’t used Mercurial and but want to give it a try then download TortoiseHg client from its homepage and install it. After installation, just go to the repository link on Bitbucket

Android – Show images from Flickr with ImageGridView

On the left menu click on Clone, and copy the selected text on popup window

Clone command

Go back to your Windows Explorer, browse to where you would like to store the code, right click on it and choose Clone on context menu

Clone repository

Paste the text from Bitbucket but remove hg clone at the beginning into Source text box. In Destination, create a folder for cloning code. Then click on Clone

Clone to folder

After TortoiseHg finishes the Clone action, you can now right click on the destination folder and choose Hg Workbench

Hg Workbench

In Hg Workbench window you’ll see all branches and histories of the code repository

Hg Workbench window

To check out a specific version, just right click on item and choose Update, you code will be exactly checked out to that version

Update to specific version

In Hg Workbench window you can also see which changes are made to code.

4. Conclusion

Bitbucket provides great service with Mercurial support. You may prefer another distributed version control but I hope this post will help you to learn more a little bit about Mercurial and download the correct version from my Bitbucket repository . Making commit, pushing changes to server are not in scope of this post because these actions must be made exactly so that the code repository couldn’t be ‘destroyed’ after a commit or a push. If you’re interesting in commit and pushing changes to code repository, search them in internet. There are a lot of good articles explaining how they should be.

Leave a comment

Your email address will not be published. Required fields are marked *