Getting Started with TortoiseHg: A Quick Guide for Beginners

Troubleshooting Common TortoiseHg Problems and Fixes

TortoiseHg is a popular graphical front end for Mercurial that makes common version-control tasks easier. Even so, users can run into issues ranging from UI glitches to repository corruption. This guide covers the most frequent problems, practical diagnostic steps, and reliable fixes so you can get back to coding quickly.

1. TortoiseHg window is slow or unresponsive

Symptoms: UI lags, committing or history rendering takes a long time, high CPU when viewing large repos.

Fixes:

• Reduce graph rendering work: In Repository Explorer (Workbench), disable or simplify graph rendering: View → Graph → set to minimal or disable changeset graph.
• Limit history range: Use View → Filter or the revision selector to show a smaller range of revisions.
• Exclude large files: Large binary files in history can slow operations. Consider using the largefiles extension or move big files to external storage and remove them from history (use hg convert or strip with care).
• Update TortoiseHg: Install the latest stable release; performance fixes are common.
• Check antivirus: Exclude your repository directory from real-time scanning or add mercurial.exe/tortoisehg processes to exceptions.
• Inspect extensions: Disable nonessential Mercurial/TortoiseHg extensions to identify conflicts.

2. “No repository found” or repository not recognized

Symptoms: Opening a folder fails to show repository; context-menu options like “Hg Commit” are missing.

Fixes:

• Confirm .hg folder exists: Ensure the repository root contains a hidden .hg directory. If missing, you’re not in a repo root—navigate up folders.
• Open correct folder: Use Workbench → File → Open Repository and select the folder with .hg.
• Permissions and hidden files: Ensure your user account can read .hg and that hidden files are visible. On Windows, check folder permissions and antivirus locks.
• File system type: Network shares or exotic filesystems may cause detection issues—clone locally or map the share differently.
• Reinitialize if necessary: If .hg is corrupted, make a copy of the working tree and clone a fresh repository from a remote source.

3. Commit fails with “abort: check for unresolved merge conflicts”

Symptoms: Commit blocked; error mentions unresolved conflicts or unmerged files.

Fixes:

• Resolve conflicts: Open the Commit dialog or Workbench; look for files marked with conflict status (typically “M” with extra markers). Use the internal merge tool (hg resolve) or an external merge tool to fix conflicts.
• Mark resolved: After resolving, run hg resolve –markor use TortoiseHg’s Resolve dialog to mark files as resolved.
• Abort merge if needed: If the merge is not desired, revert to pre-merge state with hg update –clean REV (careful: this discards uncommitted changes).
• Run hg status: Use hg status to identify unresolved files: those with “U” indicate unresolved conflicts.

4. Push/pull errors: authentication, SSL, or remote rejects

Symptoms: Push/pull fails with authentication prompts, certificate errors, or “abort: repository is unrelated”.

Fixes:

• Check remote URL: Verify the repository path in .hg/hgrc or in the Push/Pull dialog—use correct SSH/HTTPS form.
• Authentication: For HTTPS, ensure saved credentials are correct. For SSH, confirm your SSH key is loaded (Pageant on Windows for PuTTY, or ssh-agent for OpenSSH). Use hg identify https://… to test access from a shell.
• SSL certificate errors: Add the server’s CA certificate to Mercurial’s trust store or set cacerts in Mercurial.ini; avoid disabling verification permanently.
• Remote rejects (non-fast-forward): Pull remote changes and merge or rebase locally before pushing. Use hg pull; hg merge; hg commit; hg push.
• “Repository is unrelated”: You attempted to push to a repo without common history. Re-clone or fetch with hg pull –force if you understand the consequences.

5. Extensions causing crashes or strange behavior

Symptoms: Random crashes, commands not working, or inconsistent UI.

Fixes:

• Disable extensions: Temporarily disable Mercurial and TortoiseHg extensions in your config (Mercurial.ini/hgrc) and restart TortoiseHg.
• Isolate the offender: Re-enable one extension at a time to find the problematic one.
• Update extensions: Ensure extensions are compatible with your Mercurial/TortoiseHg versions.
• Use official extensions: Prefer built-in or well-maintained community extensions; avoid experimental scripts for production use.

6. File status showing modified when unchanged (line endings/permissions)

Symptoms: hg status shows files as modified though content appears identical.

Fixes:

• Line endings: Normalize line endings. Configure Mercurial’s eol extension and add a .hgeol file to enforce consistent EOLs across platforms.
• Executable bit changes: On filesystems that track permissions (Linux), Mercurial may detect mode changes. Use hg status -m to inspect, and set umask or core.filemode settings appropriately.
• Whitespace-only changes: Use hg diff to confirm. Consider converting files to a consistent text format.
• Repository clean: If safe, run hg revert –all –no-backup to revert working directory files to the last commit (this discards local edits).

7. Corrupted repository or missing revisions

Symptoms: Errors like “abort: missing changeset” or revlog corruption.

Fixes:

• Back up first: Copy the entire repository folder (including .hg) before attempting fixes.
• Run hg verify: Detect integrity issues: hg verify PATH
• Recover from bundle or clone: If available, clone from a remote mirror or use hg pull –force from another copy.
• Use hg debugrecover (advanced): Mercurial has low-level debug tools to attempt repairs—use only if you understand revlog internals.
• Restore from backup: If corruption is unrecoverable, restore from a backup or re-clone from the remote.

8. Commit/merge GUI not showing changes or missing files

Symptoms: Files present on disk not listed for commit or merge tool not showing diffs.

Fixes:

• Refresh view: Use View → Refresh or press F5 in Workbench. TortoiseHg sometimes needs a manual refresh after external changes.
• Ensure files are in repo path: Files outside the repository root or ignored via .hgignore won’t show up.
• Check .hgignore: Confirm patterns aren’t unintentionally matching files.
• File encoding or symlink issues: Some encodings or symlinked files might not be detected. Move files into standard locations and re-add.

9. Context-menu items missing in Explorer (Windows)

Symptoms: No TortoiseHg options when right-clicking repository folders.

Fixes:

• Shell extension installed: Reinstall TortoiseHg ensuring the shell extension option is selected.
• 64-bit vs 32-bit mismatch: Use the correct build for your OS; shell extension must match Windows bitness.
• Explorer needs restart: Sign out/in or restart Explorer.exe after install.
• Folder too long / network path: Long paths or network locations can hide shell extensions—map network drives or shorten path.

10. Performance problems with large clone/pull

Symptoms: Pulling/cloning large repositories is very slow or fails.

Fixes:

• Clone with –uncompressed or use bundle: hg clone –uncompressed or use hg bundle on server to transfer fewer CPU-intensive operations.
• Use shallow clone strategies: Mercurial doesn’t natively support shallow clones like Git, but you can clone a subset (hg clone -r REV or use hg convert with a filemap).
• Increase buffer/timeouts: For unstable networks, adjust HTTP buffers or use SSH transport which may be more reliable.
• Server-side maintenance: Ask remote admin to run hg verify/garbage collection or enable hg serve optimizations.

Quick diagnostics checklist

• Run hg status and hg log for basic clues.
• Use hg verify for repository health.
• Refresh TortoiseHg views after external changes.
• Check .hgignore, .hgeol, and hgrc settings.
• Temporarily disable extensions and antivirus to isolate issues.

Conclusion These steps cover the most common TortoiseHg issues and pragmatic fixes. For persistent or unusual errors, collect logs (Help → Show Log Files), back up the repository, and consider creating a fresh clone from a remote mirror.