Mercurial to Git Migration Guide

What you will learn

• Understand the core purpose of Mercurial to Git Migration Guide
• Master the basic usage and common options of Mercurial to Git Migration Guide
• A guide to migrating from Mercurial (Hg) to Git, including hg-fast-export, branch/tag conversion, and common difference handling.
• Understand key concepts: Pre-Migration Comparison
• Know when to use this feature and when to avoid it

Start with a problem

Your team is migrating from another version control system to Git, or moving code and history between different Git platforms. You're worried about losing commit history or author information during the process.

One-Sentence Understanding

Mercurial and Git are conceptually similar (both are distributed VCS), but differ in command set, branch model, and data structures. Migration requires not just data conversion but workflow redesign.

Pre-Migration Comparison

Migrate with hg-fast-export

Install Tool

git clone https://github.com/frej/fast-export.git
export PATH="$PATH:$PWD/fast-export"

Execute Migration

mkdir project-git
cd project-git
git init
hg-fast-export.sh -r /path/to/hg-repo
git checkout HEAD

Author Mapping

# authors.txt
hg_author_name <hg_author_email> = Full Name <email@example.com>

# Use during export
hg-fast-export.sh -r /path/to/hg-repo --mapping authors.txt

Handling Hg-Specific Concepts

Named Branches

Converted to Git branches by default:

git branch -a

MQ (Mercurial Queues)

Apply patches to branches before migration:

hg qfinish -a  # Convert all patches to regular commits
# Then migrate

Subrepositories

After migration, re-register Git submodules:

git submodule init
git submodule update

Post-Migration Checklist

Integrity Check

# Compare commit counts
hg log --template '{node}\n' | wc -l
git rev-list --count --all

# Compare branches
hg branches
git branch -a

# Compare tags
hg tags
git tag

Workflow Adjustments

• hg update → git checkout / git switch
• hg merge → git merge
• hg rebase → git rebase
• hg histedit → git rebase -i

Common Pitfalls

Empty Commits

Mercurial allows empty commits; Git does not by default. Some migrated commits may have no diffs — this is normal.

Hg Extensions

Large Files

Same as SVN migration — check large files and use Git LFS.

Team Transition Strategy

1. Parallel running: Both VCS for 2-4 weeks
2. Training focus: Staging area, rebase flow, PR/MR model
3. Common gotcha: Hg users tend to misuse git pull (which = hg pull && hg update)
4. Helper aliases:

git config --global alias.summary "log --oneline --graph --all"
git config --global alias.record "add -p"
git config --global alias.sync "pull --rebase"

Try it yourself

1. Practice the hg-to-git command in a test repository and observe state changes before and after
2. Experiment with different options and compare the output differences
3. Simulate a real scenario where you would need to use this, and walk through the full process

Continue Learning

1. learning-path/quick-start — Git quick start
2. workflows/squash-vs-rebase-merge — Integration strategies
3. concepts/three-layers — Git's three-layer model

Further reading

Keep going on the same topic:

• Perforce to Git Migration
• Repository Migration Strategy Guide
• Cross-Platform Git Migration