Using Bookmarks

The Mercurial project recommends the use of bookmarks for doing development.

At its core, bookmarks are a labeling mechanism. Instead of a numeric revision ID or alphanumeric SHA-1 (fragments), bookmarks provide human-friendly identifiers to track and find changesets or lines of work.


If you are a Git user, bookmarks are similar to Git branches. Although they don’t behave exactly the same.

Bookmarks and Feature Development

Bookmarks are commonly used to track the development of something - a feature in version control parlance. The workflow is typically:

  1. Create a bookmark to track a feature
  2. Commit changes for that feature against that bookmark
  3. Land the changes

Bookmarks typically exist from the time you start working on a feature to the point that feature lands, at which time you delete the bookmark, for it is no longer necessary.

Creating and Managing Bookmarks

Numerous guides exist for using bookmarks. We will not make an attempt at reproducing their work here.

Recommending reading for using bookmarks includes:

The following sections will expand upon these guides.

Getting the Most out of Bookmarks

Use Mercurial 3.2 or Newer

Mercurial 3.2 adds notification messages when entering or leaving bookmarks. These messages increase awareness for when bookmarks are active.

Integrate the Active Bookmark into the Shell Prompt

If you find yourself forgetting which bookmark is active and you want a constant reminder, consider printing the active bookmark as part of your shell prompt. To do this, use the prompt extension.

Sharing Changesets

Once you have a changeset (or several!) that you’d like to get checked into a Mozilla repository, you’ll need to share them with others in order to get them reviewed and landed.

When working with mozilla-central, pushing your changesets to user repositories is the primary method of sharing. See Managing Repositories for more information about user repositories.

Collaborating / Sharing Bookmarks

Say you have multiple machines and you wish to keep your bookmarks in sync across all of them. Or, say you want to publish a bookmark somewhere for others to pull from. For these use cases, you’ll need a server accessible to all parties to push and pull from.

If you have Mozilla commit access, you can create a user repository to hold your bookmarks.

If you don’t have Mozilla commit access or don’t want to use a user repository, you can create a repository on Bitbucket.


The Firefox repository may be larger than what Bitbucket allows you to store. If you want to share bookmarks for the Firefox repository, a user repository is your best bet.

If neither of these options work for you, you can run your own Mercurial server.

Pushing and Pulling Bookmarks

hg push by default won’t transfer bookmark updates. Instead, you need to use the -B argument to tell Mercurial to push a bookmark update. e.g.:

$ hg push -B my-bookmark user
pushing to user
searching for changes
remote: adding changesets
remote: adding manifests
remote: adding file changes
remote: added 1 changesets with 1 changes to 1 files
exporting bookmark my-bookmark


When pushing bookmarks, it is sufficient to use -B instead of -r.

When using hg push, it is a common practice to specify -r <rev> to indicate which local changes you wish to push to the remote. When pushing bookmarks, -B <bookmark> implies -r <bookmark>, so you don’t need to specify -r <rev>.

Unlike hg push, hg pull will pull all bookmark updates automatically. If a bookmark has been added or updated since the last time you pulled, hg pull will tell you so. e.g.:

$ hg pull user
pulling from user
pulling from $TESTTMP/a (glob)
searching for changes
adding changesets
adding manifests
adding file changes
added 1 changesets with 1 changes to 1 files (+1 heads)
updating bookmark my-bookmark

Things to Watch Out For

Mercurial repositories are publishing by default. If you push to a publishing repository, your Mercurial client won’t let you modify pushed changesets.

As of February 2015, user repository on are non-publishing by default, so you don’t have to worry about this. However, if you use a 3rd party hosting service, this could be a problem. Some providers have an option to mark repositories as non-publishing. This includes Bitbucket. If you plan on sharing bookmarks and rewriting history, be sure you are using a non-publishing repository.