This is a series of blogposts that consists of three parts:

(1) Part I: History of Bookmarks
(2) Part II: Daily Bookmarking
(3) Part III: Pushable Bookmarks

UPDATE I’m aware that people wait for Part II. Let me see if I can write about it this weekend…in the meantime, click the flattr button :)

I stumbled over Mercurial in August 2007. Back then I had already
used Git for 6 months, but wanted
to try out different distributed version control systems (DVCS).
I soon began to like Mercurial’s approach because of its simple and
intuitive interface and its clean codebase. While playing around
with Mercurial for a few weeks I was content with its concepts.
There was one feature missing
that I really like in Git: git-like branches.

Unlike in Mercurial or in any other version control system, branches in
Git are simply lightweight markers pointing to a commit. Every ancestor of
the commit is considered part of the branch. Back then, this sounded odd to me. Later I realized it was a really good tool to create small local branches. You can create a small branch
for a feature, merge it into your mainline, and remove the branch
without anyone knowing you ever had a branch called
‘stupid-little-feature‘. To make a long story short: It’s a good
idea to have a similar concept in Mercurial, but none existed back in 2008.

In June 2008 I started developing Mercurial References providing lightweight branches similar to those available in Git. Although the initial work was appreciated by the community, it was rejected
in favor of a concept more natural to Mercurial. Matt Mackall, the author of
Mercurial proposed Mercurial Bookmarks.

Bookmarks

The concept of bookmarks is easy:
You can bookmark a commit with a unique name. So it’s similar to
a tag, with one exception, a bookmark advanced when you commit.
(Like real bookmarks when you go to the next page).

I wrote an initial version of Mercurial Bookmarks in August, that
was finally accepted in October. This improved git like workflows
in Mercurial but still the implementation was far away from what I
wanted. By adding the notion of a so called “current bookmark”, it
got better. Still bookmarks had one major drawback in comparison
to git style branches. They were local only. There was no way to
push or pull bookmarks.

Pushable bookmarks

This was the status for the past two years. I tried to make bookmarks
pushable during this time. A proposal by me how extensions in general
can exchange arbitrary information over the wire was rejected in
early 2009 because it was too unrestrictive for the protocol. A new
concept, so called ‘pushkey concept’ was developed in 2009. This
was discussed and accepted during the Mercurial Sprint in Paris,
January 2010.

Matt Mackall, who now gets sponsored to work on Mercurial,
worked on the initial implementationof pushkey and
pushable bookmarks. And finally after two years of ongoing complains
by people about local-only bookmarks, Mercurial 1.6 will have
pushable bookmarks and introduces a great new concept to exchange
metadata information between repositories.

The next blogpost will show you how to use bookmarks.

Please note that this blog post is outdated. please refer to the mercurial help for more information about bookmarks.

A few month ago, Matt Mackall the maintainer of the Mercurial version control system, came up with the idea to implement so called bookmarks for mercurial.
Basic idea
The basic idea of these bookmarks is simple. Instead of referring to a commit by it’s linear rev number or it’s SHA1 key, the user should be able to set a bookmark on a commit and use this name to refer to the commit. So you can do:

$ hg bookmark -r 132 my-bookmark
$ hg update my-bookmark

Further thoughts
Just referring to a commit by a given name is nice, but it is not quite why we finally introduced bookmarks. A lot of people using both git and Mercurial like Mercurial for it’s simplicity and it’s clear interface. Nevertheless they are missing certain features from git and one of the most often requested are git-styled branches. Let me just give you a short overview of the differences between the branch implementation of both systems:

Mercurial branches
Mercurial branches have a lot in common with branches in Subversion or CVS. If you commit to a branch, the name of the branch is stored in the changeset and therefore an immutable part of the history. This means, unlike bookmarks, branches can not be deleted if you created them, and that you will always know to which branch a certain commit belongs.

git branches
In git’s notion of branches a branch is just a fork in the directed acyclic graph (DAG) of the history. Therefore the branch name is not recorded in the changeset. Branches are just pointers to a certain head of a DAG branch that move forward with every commit to that branch. This gives you the opportunity to create branches just for testing purposes or with stupid names that might be merged or rebased later. If you delete the branch name, the branch in the DAG resides, but the name is gone.

As bookmarks are also just pointers to commits in the history, it is quite obvious that it is easy to implement a mechanism equal to the branch mechanism of git. Therefore bookmarks are not just pointers, but they move forward to the next commit if you create a child commit on a commit that is referred by a bookmark.

Problems
As the branch notion in mercurial is different from git, it is clear the the internal design of mercurial makes some assumptions that rely on this behavior. This leads to some design decisions that might confuse people that come from git. If you switch to a branch in git and commit to it, only the branch that you are on is moved forward even though the parent commit has two branch names. Mercurial bookmarks are always forwarded if the parent commit is referred by a bookmark. Therefore you might forward bookmarks on commit without evening knowing. We don’t have a notion of a current bookmark. Furthermore bookmarks are local. There is no way to push or pull bookmarks. This is a limitation by the wire protocol of mercurial. There are patches floating around that implement a way to bring push/pull mechanism for various data including bookmarks, but as the wire protocol is a critical part of mercurial, the developer usually don’t like to enhance or change the protocol. You can use bookmarks remotely and do a lookup on them, but it requires a certain amount of deep knowledge.

Implementation
As already mentioned, we have a working bookmark implementation now. I worked on these bookmark stuff for several months. With the help of the mercurial community we finally made our way to the main tree (mpm’s and the crew tree) and therefore my extension will be part of the upcoming Mercurial 1.1 release. I’m currently maintaining the bookmarks on bitbucket.org and a crew member is usually merging changes from me into the crew tree from time to time.

Example
Let’s give you a short example how bookmarks work. First of all we have to checkout recent versions of Mercurial. You can get an hourly snapshot here. Then we have to setup the extension by adding the following lines to our ~/.hgrc:

[extensions]
hgext.bookmarks =

Now let’s go into a Mercurial repository. You can run hg help bookmarks to show the available flags.
Let’s start with a basic listing of available bookmarks:

$ hg bookmarks
no bookmarks set

Create a bookmark on the current tip of the repository:

$ hg bookmark my-tip
$ hg bookmarks
+ my-tip 7348:1a5c9ca2bfd5

Let’s create a bookmark on an other revision in the history:

$ hg bookmark -r 7300 hgweb-fix
$ hg bookmarks
+ my-tip 7348:1a5c9ca2bfd5
hgweb-fix 7300:591767e6ea7a

We can than update to the revision:

$ hg update hgweb-fix
82 files updated, 0 files merged, 31 files removed, 0 files unresolved
$ hg bookmarks
my-tip 7348:1a5c9ca2bfd5
+ hgweb-fix 7300:591767e6ea7a

We also can now commit to this bookmark and create a new head:

…hack..hack..
$ hg commit -m’Another hgweb bugfix’
$ hg bookmarks
my-tip 7348:1a5c9ca2bfd5
+ hgweb-fix 7349:ca3fbad32554

Let’s go back to our tip and merge our change into it:

$ hg update my-tip
$ hg merge hgweb-fix
$ hg commit -m’Merge bookmark hgweb-fix’

Now we can just delete our bookmarks

$ hg bookmark -d hgweb-fix
$ hg bookmarks
+ my-tip 7350:3acda44343da

You can use bookmarks in every rev lookup. This means you can also do hg log my-tip or hg qimport -r my-tip. It is even possible to look them up using hg id -r . I hope you enjoy it. If you encounter any bugs don’t hesitate to file an issue at the mercurial bugtracker.

Thanks to
A lot of people were involved in the development of the bookmarks extension either by giving ideas or by actually patching it. Thanks to ronny, mpm, tonfa, piranha, parren, joel, dimitriy and #mercurial.

Links

• Mercurial
• Crew repository
• Announcement of the bookmark extension
• My bookmark repository

Mercurial is a fast decentralized version control system used by projects like Mozilla and OpenJDK for their software development. It is written in python and currently maintained by Matt Mackall.