Mercurial (Hg)

Mercurial (hg) is a free, distributed version control system designed for efficient handling of large projects. This guide covers common commands for working with repositories, commits, and collaboration.

Installation

macOS

brew install mercurial
hg --version

Linux/Ubuntu

sudo apt-get update
sudo apt-get install mercurial

Windows

choco install mercurial
# Or download from https://www.mercurial-scm.org/download

Basic Commands

Command	Description
hg --version	Show Mercurial version
hg help <cmd>	Get help for command
hg init	Initialize new repository
hg clone <url>	Clone existing repository
hg status	Show repository status
hg log	Show commit history
hg add <file>	Stage file for commit
hg commit	Create new commit
hg push	Push changes to remote
hg pull	Pull changes from remote

Repository Setup

Initialize Repository

# Create new repository
hg init my-project
cd my-project

# Clone existing repository
hg clone https://bitbucket.org/user/project
hg clone ssh://hg@bitbucket.org/user/project

# Clone into specific directory
hg clone <url> ./target-dir

# Verify repository
hg verify

Configuration

# Configure user identity
hg config --local user.name "John Doe"
hg config --local user.email "john@example.com"

# View configuration
hg config user

# Global configuration (~/.hgrc)
[ui]
username = John Doe <john@example.com>
editor = vim

[paths]
default = https://bitbucket.org/user/project

[extensions]
rebase =
evolve =

Working with Changes

Checking Status

# Show repository status
hg status

# Show changes in working directory
hg diff

# Show changes for specific file
hg diff filename.txt

# Show status with copies/renames
hg status -C

Adding and Removing Files

# Add new file
hg add file.txt

# Add all new files
hg add

# Remove file
hg remove file.txt

# Rename/move file
hg rename oldname.txt newname.txt
hg mv oldname.txt newname.txt

# Copy file
hg copy file.txt file-copy.txt

# Remove and commit in one step
hg remove file.txt && hg commit -m "Remove old file"

Committing Changes

Basic Commits

# Commit with message
hg commit -m "Fix bug in login"

# Commit with longer message
hg commit -m "Feature: Add user authentication" -l commit-message.txt

# Commit specific files
hg commit file1.txt file2.txt -m "Update docs"

# Commit interactively (choose hunks)
hg commit --interactive

# Amend last commit
hg commit --amend -m "Updated message"

# Commit without adding files first
hg commit file.txt -m "Add file and commit"

Viewing History

# Show commit log
hg log

# Show last N commits
hg log -l 10

# Show commits for specific file
hg log filename.txt

# Show commits from author
hg log -u "John Doe"

# Show with patch
hg log -p

# Show graph of branches
hg log -G

# Show commits in date range
hg log -d "2025-03-01 to 2025-03-31"

# Show specific commit
hg log -r 42
hg log -r "2025-03-30"

Branching and Merging

Named Branches

# Create new branch
hg branch feature/new-feature

# Check current branch
hg branch

# List all branches
hg branches

# Switch branch
hg checkout branch-name

# Close branch
hg commit --close-branch -m "Close branch"

Bookmarks (Like Git Branches)

# Create bookmark
hg bookmark my-feature

# List bookmarks
hg bookmarks

# Switch to bookmark
hg checkout my-feature

# Rename bookmark
hg bookmark -r my-feature my-new-feature

# Delete bookmark
hg bookmark -d my-feature

# Push bookmark
hg push -B my-feature

Merging

# Merge branch
hg merge branch-name

# Merge specific revision
hg merge -r revision-id

# Preview merge (don't commit)
hg merge --preview branch-name

# Resolve conflicts
hg resolve -l           # List conflicts
hg resolve -m file.txt  # Mark as resolved
hg resolve --all        # Resolve all

# Complete merge
hg commit -m "Merge branch-name"

# Abort merge
hg merge --abort

Pushing and Pulling

Pull and Fetch

# Pull changes from remote
hg pull

# Pull specific remote
hg pull -R remote-name

# Pull and update working directory
hg pull -u

# Check incoming changes
hg incoming

# Pull specific changeset
hg pull -r 42

Push

# Push changes
hg push

# Push to specific remote
hg push ssh://hg@bitbucket.org/user/project

# Check outgoing changes
hg outgoing

# Force push (use with caution)
hg push --force

# Push specific bookmark
hg push -B my-feature

# Push to multiple remotes
hg push path1 && hg push path2

Rebasing and History Rewriting

Rebase

# Rebase current branch onto another
hg rebase -d branch-name

# Rebase range of commits
hg rebase -s source -d destination

# Continue rebase after resolving conflicts
hg rebase --continue

# Abort rebase
hg rebase --abort

Updating

# Update to specific revision
hg update 42
hg update branch-name
hg update "2025-03-30"

# Update to parent revision
hg update -r .^

# Update and discard changes
hg update -C revision

Advanced Operations

Cherry-picking

# Import specific commit from another branch
hg graft commit-id

# Cherry-pick multiple commits
hg graft -r "commit1::commit3"

# Continue after resolving conflicts
hg graft --continue

# Abort graft
hg graft --abort

Shelving Changes

# Shelve current changes
hg shelve

# Shelve with description
hg shelve -n "WIP: feature-x"

# List shelved changes
hg shelve -l

# Restore from shelf
hg unshelve

# Delete shelf
hg shelve -d shelf-name

# Show shelved changes
hg shelve -l -p

Reversing Changes

# Revert file to previous state
hg revert filename.txt

# Revert all changes in working directory
hg revert -a

# Revert to specific revision
hg revert -r 40 filename.txt

# Create new commit that reverts changes
hg backout commit-id
hg backout -r 40

Remote Repositories

Managing Remotes

# Show remote paths
hg paths

# Add remote
hg paths.default = https://bitbucket.org/user/project

# List all remotes (in .hg/hgrc)
cat .hg/hgrc

# Set default remote
echo "[paths]" > .hg/hgrc
echo "default = https://bitbucket.org/user/project" >> .hg/hgrc

Synchronizing

# Fetch all remotes
hg pull -u

# Fetch from multiple remotes
hg pull remote1 && hg pull remote2

# Sync fork with upstream
hg pull upstream
hg rebase -d upstream/default

# Push to multiple remotes
hg push && hg push backup-remote

Collaboration Workflows

Feature Branch Workflow

# Create feature branch
hg bookmark feature/auth-system

# Make changes
echo "auth code" > auth.py
hg add auth.py
hg commit -m "Add authentication system"

# Push feature branch
hg push -B feature/auth-system

# Merge to main
hg checkout default
hg merge feature/auth-system
hg commit -m "Merge feature/auth-system"
hg push

Review Process

# Push for review
hg push -B review/feature-x

# Get feedback and update
# ... make changes ...
hg commit --amend -m "Updated per review"
hg push --force -B review/feature-x

# After approval, merge
hg merge review/feature-x
hg commit -m "Merge review/feature-x (reviewed)"
hg push

Useful Extensions

# Enable in .hgrc
[extensions]
color =
rebase =
evolve =
histedit =

Common Extensions

# Rebase extension
hg rebase -d main

# Evolution (better history editing)
hg evolve

# Interactive history editor
hg histedit

# Color output
hg log --color=always

# Shelve/unshelve
hg shelve

Troubleshooting

Merge Conflicts

# See conflicts
hg status

# Resolve conflicts manually
vim conflicted-file.txt

# Mark as resolved
hg resolve -m conflicted-file.txt

# Resolve all
hg resolve --all

# Complete merge
hg commit -m "Merge resolved"

Undo Changes

# Discard uncommitted changes
hg revert filename.txt
hg revert -a

# Undo last commit (keep changes)
hg uncommit

# Undo last commit (discard changes)
hg strip -r .

# Restore deleted file
hg revert filename.txt

Repository Issues

# Verify repository integrity
hg verify

# Fix repository
hg recover

# Check for corruption
hg check

# Rebuild dirstate
hg status

Useful Aliases

[alias]
st = status
co = checkout
ci = commit
br = branch
up = update
lg = log -G
ld = log --date=short
who = log -u

Resources

• Mercurial Official Site
• Mercurial Tutorial
• Bitbucket Mercurial Guide
• Mercurial Commands

---

Last updated: 2025-03-30