• Migrating from Mercurial to Git

    A long column of wildebeest fording a blue-green river from a dry bank toward a green one

    Sometimes you need to keep working on old projects that may use outdated version control systems, such as Mercurial or, God forbid, SVN. Fortunately, to move from Mercurial to Git you do not need to start the project from a clean slate and lose the history of changes; there is a utility that will do everything for us by itself.

    bash
    cd
git clone https://github.com/frej/fast-export.git
git init git_repo
cd ~/git_repo
~/fast-export/hg-fast-export.sh -r ~/mercurial-repo
git checkout HEAD

    As a result, in the current folder we will get a real Git repository.

    Update, October 2026

    The recipe above still matches the tool’s own README, with one change: the maintained home of fast-export is now github.com/frej/fast-export, so the clone line uses that URL instead of the original git://repo.or.cz/fast-export.git mirror. The mirror still works, but git:// has no transport security, so HTTPS it is.

    A few things worth knowing before you trust the result:

    • It needs Python 3.7+ and the mercurial Python package 5.2+ (pip install mercurial).
    • Mercurial is lax about author strings and Git is not. Collect the authors with hg log --template "{author}\n" | sort | uniq, map the odd ones in a file, and pass it with -A authors.map.
    • It handles only named branches with exactly one head each. Extra heads either get flattened or stop the export; the README covers the options.
    • The default branch becomes master. Use -M main if that is what you want.
    • Compare branches, tags, and commit counts between the two repositories before you delete the Mercurial one.

    GitHub’s own Mercurial import guide follows the same flow, with those extra steps spelled out.

Read next