Mercurial Bookmarks Guide – Lightweight Branching

Learn how to create, use, and recover Mercurial bookmarks for lightweight branching, with step‑by‑step commands, verification steps, and recovery tips.

Desired Outcome

You want a movable pointer (bookmark) that tracks a specific changeset in a Mercurial repository, allowing you to switch between lines of work quickly without creating heavyweight named branches.

Prerequisites

A Mercurial repository initialized with hg init or cloned from a remote.
Mercurial version 2.0 or later (bookmarks became stable in this series).
Basic familiarity with hg update, hg commit, and hg parents.
Read/write access to the repository directory.

Procedure

Navigate to the target changeset
Ensure your working directory is at the revision you want the bookmark to point to.
```
hg update -r <rev>
```
Replace <rev> with a changeset hash, revision number, or a symbolic name like tip.
Create the bookmark
Assign a name to the pointer.
```
hg bookmark <bookmark-name>
```
The bookmark is now stored locally and points to the current changeset.
Switch to the bookmark
Update your working directory to the bookmarked revision.
```
hg update <bookmark-name>
```
Commit work and let the bookmark move
After making changes and committing, the bookmark automatically advances to the new tip.
```
hg commit -m "Describe changes"
```
No extra command is needed; the bookmark follows the commit.

Rename or delete a bookmark (optional)

# Rename
   hg bookmark -r <old-name> <new-name>
   # Delete
   hg bookmark --delete <name>

Share bookmarks with others

By default bookmarks are not transmitted; you must push or pull them explicitly.

# Push a specific bookmark
   hg push -B <bookmark-name>
   # Pull a specific bookmark into another clone
   hg pull -B <bookmark-name>
   hg update <bookmark-name>

Expected Checks

List bookmarks to confirm creation: hg bookmarks (look for an asterisk * next to the active bookmark).
Verify the working directory parent matches the bookmark: hg parents should show the same changeset hash as the bookmark.
After a commit, run hg parents again; the hash should have advanced and the bookmark should still be active.
To test sharing, push the bookmark with hg push -B <name>, then in a separate clone run hg pull -B <name> followed by hg update <name> and confirm the working directory is at the expected revision.

Recovery Options

Recreate a lost bookmark: Use the reflog to find the changeset it previously pointed to.

hg log -r 'bookmark(<name>)'   # shows history if still present
   hg log -r 'all()'               # full search if needed
   # Once you have the changeset hash <rev>:
   hg bookmark <name> -r <rev>

Force‑move a bookmark (if you need to point it elsewhere):
```
hg bookmark -f <name> -r <new-rev>
```
Divergent bookmark after pull: If the remote moved the bookmark ahead of your local copy, merge the heads and then update.
```
hg merge
   hg commit -m "Merge heads"
   hg update <bookmark-name>
```

Limitations and Practical Verification

Bookmarks are lightweight pointers; they are not part of the immutable changeset history and can be lost if not pushed. To ensure a bookmark is persisted, always push it with -B after creating or moving it. You can verify persistence by checking the remote repository:

# On the server or another clone
   hg bookmarks

If the bookmark appears, it has been successfully shared.

Example Workflow

Suppose you have a repository at /srv/hg/project and you want a bookmark named feature/login to track work on a new login form.

# 1. Update to the base revision (e.g., tip of default)
   hg -R /srv/hg/project update -r tip

# 2. Create the bookmark
   hg -R /srv/hg/project bookmark feature/login

# 3. Make changes, commit
   hg -R /srv/hg/project commit -m "Add login form skeleton"
   # Bookmark feature/login now points to this new commit

# 4. Share the bookmark
   hg -R /srv/hg/project push -B feature/login

# 5. On a teammate’s clone
   hg -R /home/alice/project pull -B feature/login
   hg -R /home/alice/project update feature/login
   # Working directory is now at the same changeset as the bookmark

If you later decide the bookmark name should be ui/login, rename it:

hg -R /srv/hg/project bookmark -r feature/login ui/login

To delete the old name after confirming the new one works:

hg -R /srv/hg/project bookmark --delete feature/login

Creating and Managing Mercurial Bookmarks for Lightweight Branching