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:
- Create a bookmark to track a feature
- Commit changes for that feature against that bookmark
- 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.
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
$ 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
hg push, it is a common practice to specify
<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
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 hg.mozilla.org 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.