Diagnosing and Fixing Common Mercurial Bookmark Issues

Problem Overview

Bookmarks in Mercurial let you mark a specific changeset with a friendly name, similar to Git tags but mutable. When a bookmark behaves unexpectedly—disappears after a push, conflicts after a rebase, or lingers as an orphan—your workflow can stall. This guide gives you a concise, ordered diagnostic path to identify the root cause, apply the appropriate fix, and know when to involve your team.

Recognizable Conditions

Below are three conditions that most Mercurial users encounter with bookmarks. Each condition is paired with a likely cause and a quick test.

Ordered Diagnostic Checks

1. Verify Bookmark Presence on All Clones

   Run hg bookmarks in each clone. If a bookmark appears locally but not remotely, skip to step 3.

2. Confirm Remote Bookmark Support

   Remote Mercurial servers (e.g., hg serve, Bitbucket, GitHub) must support bookmarks. Check the server's hg help config or documentation for allowbookmarks. If absent, bookmarks aren't stored.

3. Check Push Flags

   Push bookmarks with hg push --bookmark or hg push -B. Without the flag, bookmarks are not transmitted. Example: hg push -B feature pushes only the feature bookmark.

4. Inspect Bookmark History for Duplicates

   Run hg log --template=\"{rev}:{node|short} {bookmark}\\n\". If the same bookmark name appears on two different revisions, a conflict exists.

5. Search for Orphaned Entries

   Open .hg/bookmarks and verify each line maps to a valid changeset hash. Remove any line that doesn't.

6. Validate Working Directory State

   After cleaning .hg/bookmarks, run hg update to ensure the working directory reflects the correct bookmark head.

Fixes Tied to Findings

1. Missing Bookmark After Push

Fix: Push with the bookmark flag and enable bookmark support on the server.

# Push a single bookmark
hg push -B feature

# Or push all bookmarks
hg push --bookmark

Risk: If the remote is read-only or bookmarks are disabled, the push will fail. Verify allowbookmarks=true in the remote's hgrc or ask the admin.

2. Bookmark Conflict After Rebase

Fix: Rename one of the conflicting bookmarks or collapse the changesets.

# Rename conflicting bookmark
hg bookmark -r 12345 new-feature

# Collapse bookmarks if they point to the same head
hg bookmark -f -r 12345 new-feature

Risk: Renaming changes the history visible to collaborators. Communicate changes before pushing.

3. Orphaned Bookmark Entry

Fix: Edit .hg/bookmarks to delete stale lines, then run hg update to sync.

# Edit .hg/bookmarks
# Remove lines that reference missing changesets
# After editing
hg update

Risk: Manual editing may corrupt the file if syntax is incorrect. Always back up .hg/bookmarks before editing.

Escalation Criteria

Use the following thresholds to decide when to involve teammates or a repository admin:

• Bookmark missing on multiple clones – Verify remote support; if missing, contact the server admin.
• Bookmark conflict after rebase that affects public history – Coordinate with collaborators; rebase may rewrite history.
• Persistent orphaned bookmarks after cleanup – Check for repository corruption or permission issues; consider cloning a fresh copy.

Verification Steps

To confirm the fix worked:

1. Create a fresh clone: hg clone https://example.com/repo newclone.
2. Add a bookmark: hg bookmark feature, commit, and push with --bookmark.
3. Pull in another clone: hg pull and hg update.
4. Run hg bookmarks – the feature bookmark should appear.

For rebase tests, after rebasing on a bookmark, hg bookmarks should show the updated head. If the bookmark name changes, verify the rename was intentional.

Limitations and Practical Checks

Bookmark support varies by server version. Mercurial 4.0+ includes out-of-the-box support, but older servers may require manual configuration. Always check hg help config on the remote. Additionally, bookmark operations are not atomic; if a push fails midway, you may end up with half-applied bookmarks. Use hg status and hg log to confirm consistency.

Conclusion

By following the ordered checks and applying the targeted fixes above, most bookmark-related hiccups in Mercurial can be resolved quickly. Remember to keep backups, coordinate with collaborators on history-rewriting operations, and verify remote support before pushing bookmarks.