Mercurial to Git Migration Guide

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"

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