Mercurial bookmarks

First TeamCity 8.0 EAP brought a Mercurial bookmarks support. Let’s see how you can use them with TeamCity.

Mercurial bookmarks are lightweight branches like those you have in Git. While a regular Mercurial branch is a property of a commit and cannot be changed once commit is published, bookmarks can be changed in any way you want: you can add bookmarks to existing commit, you can change the commit a bookmark points to, you can easily delete a bookmark and most importantly you can share them with others. If you are new to bookmarks this tutorial might be useful.

In TeamCity bookmarks can be used in branch and branch specification fields of VCS root settings just like regular branches.

I can see the following uses of bookmarks:

• feature branches with bookmarks
• using bookmarks to narrow changes detected by TeamCity

Feature branches with bookmarks

You can share you work with others (and with TeamCity) by pushing bookmarks to a Mercurial server. There is one caveat though. Since every commit still has a branch, this branch becomes multiheaded. It doesn’t make sence to track such a branch in TeamCity since its current revision is the latest pushed head and it constantly changes. It’s better to create a bookmark, e.g. main, which points to the tip of mainline of development, use it in the branch field and exclude the regular branch in which you create bookmarks from branch specification.

Narrowing detected changes

Let’s say you use regular Mercurial branches to share work with your peers and you have several dozens of branches. Let’s also say that you don’t work on a single branch until it is completely finished, but frequently switch between branches. You have +:* in your branch specification and TeamCity detected all of your branches.

The problem is: your complete build chain, which tests the product on different platforms under different environments, takes half a day to run and you don’t want to waste resources by running build on not yet finished work. On the other hand, you want to publish your work so other can use it. Bookmarks to rescue! All you need is to modify your branch specification to something like +:(*)@ci and publish a bookmark with an appropriate name, such as new.feature@ci, that points to the branch tip once the branch is ready for the build. You can continue to share you work using regular branches and TeamCity will detect only changes you want it to detect.

As you can see, bookmarks can help to implement some useful workflows. All you need to try them is Mercurial 2.4 installed on TeamCity server and of course your Mercurial server should support bookmarks. If you have any other interesting workflows – feel free to share them in the comments. Happy branching!