Using Mercurial with BitBucket


In this blog post I’m going to demonstrate the basics of setting up a repository in Bitbucket and then using Mercurial or rather, Tortoise Hg to push and pull software from the Bitbucket repository.

The Bitbucket Account

You can sign up for a Bitbucket account for free.  I would recommend that everyone who develops software to get familiar with repositories and version control by practicing with something like Bitbucket and Mercurial.  Bitbucket allows an unlimited number of private repositories for you to store your source code.  Once you sign up for an account and activate it, you can log in and see the Dashboard:

Under the “Repositories” menu is a “Create Repository” command that you can use to create a new repo:

Make sure you select Mercurial and you can optionally select the language of your overall project.  Give your repo a name and create it.  Then you’ll see it show up in your dashboard.  In this blog post I created a repo named “Demo Repository” (the Tutorial repo came with the account).

Now you’re ready to make a clone on your desktop so you can push your initial project up to the repository.  Click on the repository link in the dashboard and you’ll see this screen:

Click on the “…” and Clone.  Then you will see a command line that you can copy (by right clicking or just use Ctrl-C).  Then you’ll need to go to your desktop and create a directory to put this repository in.  I created a directory named bitbucket on my E: drive.  Start a command from your start menu by typing “cmd” in the search box of your start menu:

In your command window, navigate to your directory, then paste (you’ll have to right-click and select paste in order to paste it into the command window).  The clone command from bit bucket should show and then you can press the enter key to execute the command.  This will cause Bitbucket to ask for your password.  Enter your password and press enter, then the rest of the changes will be pulled down.  Initially, there are no changes and a connection with your repo is setup but the directory is pretty much empty (there is a .hg directory for your mercurial settings).  Now you can close your command window.

Using Mercurial or Tortoise Hg

First, let’s copy something into your local repo directory so we can push it up to Bitbucket.  For this demo I created a console application with Visual Studio 2012 and named it BitbucketDemoApp.  Create your app inside the repo directory that you created, or copy an existing application into this directory.  This application should reside here permanently.  My console application is just the startup application.  Nothing special.

Next go to this website: and click the download button.  Download the application and install it.  Navigate to your bitbucket directory (the one that you created your repo inside of).  Right-click on your repo directory and select “Hg Workbench”.  My repo directory is named “demo-repository”, that’s the name that Bitbucket setup from the repo name inside of the Bitbucket website.

Click on the “default” in the top pane.  You should see a bunch of pink filenames.  Those are files that are new and do not exist in the Bitbucket repository yet.  You can click the check box near the “filter text” section to select all files.  In the right pane (named “Parent:”) you can give a description.  I typed in “initial check-in”.  Click on the “commit” button.

A screen will appear that forces you to identify yourself, just type in the name you used in Bitbucket.  Then a “confirm add” dialog will show up and you can click the “add” button to add your files.  At this point, you have committed your files to your local repository.  They are not on Bitbucket yet.  In order to push your files to Bitbucket, you will use the push button:

Once you press this button, you’ll be asked to confirm.  Click “Yes” and you’ll be asked to enter your Bitbucket password.  After you enter your password your changes will be transmitted up to Bitbucket.  A green bar near the menu bar will show that your push completed successfully.
Now go to Bitbucket and you’ll see that there is one commit under the “recent activity” section:

If you click on the “1 commit” link, you’ll see a screen that shows all the files you have committed and what changes have taken place since your last commit (which is none, since this is the first commit).

Create a Branch

Your default branch should always be the stable running version until you are ready to deploy a new version of software.  The way you control this is to create a branch for each bug-fix and enhancement you make to your software.  You can create hundreds of branches at once.  Sometimes this gets a bit tricky to keep track of what is going on in your software so TrotoiseHg has a visual aid to show you each version committed to the repository and each branch that is currently open.  So, let’s make a tiny change and put it on a branch.

First, I went into my console application and added a line of code:

Then I saved my changes and closed my Visual Studio (sometimes Visual Studio doesn’t save the solution file changes until you close VS, so always close up before committing changes).

Now go back to TortoiseHg (right-click on your repo directory and select “Hg Workbench” unless you left the window open from the last use.  Sometimes you’ll have to click one of the refresh buttons to get your changes to show up in the file list window:

You should see one or two file changes.  The source code you changed and possibly the solution and/or project file.

Now type in a comment.  I typed in “Added Console Write” to my comment.  This is what my window looks like now:

Now you need to create a branch.  Click on the “Branch:default” button (it doesn’t look like a button because it’s flush with the window, just click it). Select “Open a new named branch” and give it a name:

Click the commit button.  You will get a confirm new branch window, click “Create Branch”.  Your changes are now committed to your local repository.  If you are working in a multi-programmer environment, someone else could have committed to the repository since you made your change.  In this instance, you’ll need to pull changes.  So click on the pull button (it’s a good habit to get into):

Enter your password (I’ll show you how to get this annoying screen to go away later in this article).  Then you should get a message that the pull completed.  If there were any changes from other programmers, their branches and versions will appear in your window.  If someone changed something that you also changed, there could be a conflict that you’ll need to work out.  I will not be covering conflicts in this blog post.  This post is just to get you warmed up.

Now push your changes to Bitbucket using the push button like before:

Enter your password, and click yes to “Confirm New Branch”.  Enter password again…sigh.

Now if you go to your Bitbucket account and refresh your browser, you’ll see another “1 commit”.  This is your latest version.  Clicking on that link will show the tiny bit of code that you changed:

Now if you look at your TortoiseHg window, you’ll see 3 dots.  Going from bottom to top, one blue dot is your default branch at revision zero.  That was your initial check-in.  The next dot up is a green dot (assuming TortoiseHg uses the same colors), that is revision 1 and it is under a different branch name (Console-write-enhancement in my example).  Then there is a dot on top that is always under the description “Working Directory”.  This is going to be your next revision when you commit your next change:

Switch Branches

Let’s switch back to your default branch.  In TortoiseHg right-click on the default branch line and select “update” a window will appear, just click the “update” button.  Now you’ll see this:

Now the working directory is on the default branch.  At this point you can make changes to default and check those changes in.  But more importantly, if you go back to Visual Studio, you’ll notice that your Console.Write command is gone.  That’s because that change occurred on the other branch.

Merge Branches

Let’s merge our enhancement back into the default branch and then close the enhancement branch.  This is going to take a few steps:

1. Right-click on the “console-write-enhancement” branch and select merge with local.  A window should pop-up and you can click the “next” button to continue.  Everything should run smooth and you can click the “Next” button from this window.  Then there is a “Commit Now” button that you must click followed by a Finish button in order to complete the operation.

2. Push your merged changes back up to Bitbucket.

You should end up with something like this:

Now you need to switch back to your branch.  You can actually continue to make changes and then merge your changes again at a later time, but we’re going to close this branch.  So right-click on the green dot and select “Update”.  Then click the “update” button on the window that appears.

Now you need to click on the working directory dot at the top and then click the “Branch: Console-write-enhancment” button that doesn’t look like a button.  Select “Close current branch”:

Click “OK”, then click the “commit” button.  Some red text will tell you that the head is closed.  Now click the push button.  Last, you must switch back to your default branch before you attempt any other changes in your source code.  Right-click on default and select “Update”.  If you change a closed branch, it will become un-closed.  Remember this handy little hint, in case someone accidently closes the default branch and you decide you need to open it back up.  Just commit another change and the branch is no longer closed.

Embedding the Password

In TortoiseHg, go to the File menu and select “Settings”There is an “Edit” button in the upper right corner, click that to edit the mercurial.ini file.  Then add this to your file:


Click “Save” then “OK” and then you can push or pull.  The first time, you’ll be asked to enter your password, after that TortoiseHg will not ask for your password again.


This blog post is nothing more than an introduction to handling repositories with Mercurial using TortoiseHg and Bitbucket.  You can get pretty far with just this information.  I’ll continue with future blog posts about how to undo mistakes and some examples of daily operations using branching and merging.  But for now, practice with these tools and get comfortable with branching and merging.