Mirror a Mercurial repository, including nested Mercurial subrepositories, into a Git monorepo.
The tool keeps each Mercurial subrepo under its matching path inside the Git mirror and records sync state in the mirror repository so later runs only apply new commits.
- Python 3
- Git available on
PATH - Mercurial (
hg) available onPATH
There are no third-party Python package dependencies. The script uses only the Python standard library.
Run the script from any directory and pass both the source Mercurial root and the destination Git mirror path.
python hgit-mirror.py --root D:\path\to\hg-project --mirror D:\path\to\git-mirror --initBy default, initial setup imports the most recent 100 commits from each discovered repo. To change that:
python hgit-mirror.py --root D:\path\to\hg-project --mirror D:\path\to\git-mirror --init --recent-commits 250Use --recent-commits 0 to import the complete history of each included repo.
To configure and push to GitHub during setup:
python hgit-mirror.py --root D:\path\to\hg-project --mirror D:\path\to\git-mirror --init --remote git@github.com:user/repo.gitAfter the mirror has been initialized, run:
python hgit-mirror.py --root D:\path\to\hg-project --mirror D:\path\to\git-mirrorTo sync and push:
python hgit-mirror.py --root D:\path\to\hg-project --mirror D:\path\to\git-mirror --remote git@github.com:user/repo.gitpython hgit-mirror.py --root D:\path\to\hg-project --mirror D:\path\to\git-mirror --interactiveInteractive mode shows pending commits per subrepo and provides menu actions for init, sync, push, sync plus push, and setting the remote URL.
Use --exclude to keep subrepos, directories or files out of the mirror:
python hgit-mirror.py --root "D:\code\projects\aamp (2)" --mirror D:\path\to\git-mirror --init --exclude regression --exclude AGENTS.mdExclude patterns are saved in the state file, so later syncs (including the refresh script) keep applying them without repeating the flags. Use --unexclude PATH to remove a saved pattern. Both flags can be repeated.
Patterns are paths relative to the mirror root:
regressionexcludes that subrepo or directory and everything below it.AGENTS.mdexcludes only the file at the mirror root.- Glob patterns are matched with
fnmatch, so*AGENTS.mdexcludes the file at every level.
Adding an exclude to an existing mirror commits the removal of the matching files with the generic message Update mirror exclusions. Earlier Git history still contains them; create a fresh mirror with --init if they must be gone from history. Un-excluding a subrepo seeds it with a snapshot of its latest revision.
Use repeatable --redact TEXT options to replace sensitive terms in commit messages with ***:
python hgit-mirror.py --root D:\private\aamp --mirror D:\private\aamp-git --init --recent-commits 0 --exclude regression --exclude AGENTS.md --exclude "*/AGENTS.md" --redact "Sensitive Project" --redact "Client Name"Matching is literal and case-insensitive, including matches inside longer words, paths, and URLs. Each match becomes exactly three asterisks. Overlapping terms are matched longest-first in one pass. Blank terms are rejected.
The full message (subject and body) is preserved with these replacements. Generated commit messages and message previews use the same replacements. Redaction terms are saved in the state file inside .git, so later syncs, the refresh script, and interactive operations reuse them. Repeating --redact adds terms to the saved list, even when there are no pending commits.
Exclusions control imported paths; redaction controls message text. Excluded names do not automatically become redaction terms. Included file contents, paths, and author identities are unchanged. New redaction terms apply to future imports; recreate the mirror to apply them to all history.
Both initial conversion and later syncs discard revisions whose filtered tree has no changes. This includes revisions that only change excluded files or Mercurial metadata, such as subrepo pointers. Their messages do not become Git commits. Mixed revisions retain their included changes and use the redacted message.
Skipped revisions still advance the sync state and are reported separately, so later runs do not retry them. A first snapshot containing included files creates a seed commit even if that revision originally changed only an excluded file. Its message is also redacted.
A fresh mirror with no included files remains without a Git commit until there are included changes (or generated Git metadata). Application failures stop the run, preserving the last successfully processed revision.
- Discovers subrepos by recursively reading
.hgsubfiles. - Collects new Mercurial commits per repo using
hg log -T json. - Applies commits to the Git mirror in chronological order.
- Rewrites subrepo patch paths so each subrepo lands under the correct monorepo directory.
- Converts
.hgeolto.gitattributesand.hgignoreto.gitignoreduring initial setup. - Stores the last synced Mercurial revision per repo in
.git/hg-mirror-state.json.
Initial setup uses full snapshots for each imported commit because a partial history window may not contain the parent commits required for patch application. Incremental sync uses hg diff --git -c and git apply --index, then creates a commit with the sanitized message, original author, and original author date. Messages are sanitized before committing.
The default state file is:
<mirror>/.git/hg-mirror-state.json
A convenience refresh script is also written to:
<mirror>/.git/hg-mirror-refresh.bat
Both files live inside .git, so they are not committed to the mirror repository.
Use --state-file PATH to override the state file location.
Preview what would happen without writing changes:
python hgit-mirror.py --root D:\path\to\hg-project --mirror D:\path\to\git-mirror --dry-run- The mirror directory must not already contain a Git repository when using
--init. - If
--remoteis omitted, the script syncs locally and skips pushing. - Mercurial metadata files such as
.hgsub,.hgsubstate,.hgeol,.hgtags, and.hgignoreare excluded from mirrored content. .hgignoreregular-expression patterns cannot be converted exactly to.gitignore; the generated.gitignorecomments those patterns for manual review.
Run the regression suite with Python, Git, and Mercurial installed:
python -B -m unittest -v test_hgit_mirrorThe tests create disposable repositories and do not modify your source repositories or mirrors.