# 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.

Tip

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 or the scm-prompt.sh script from Facebook’s hg-experimental repository.

## 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.

Warning

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  Tip 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