Troubleshooting Common TortoiseHg Issues and Solutions

TortoiseHg Tips and Tricks: Boost Your Mercurial WorkflowTortoiseHg is a graphical front-end for the Mercurial distributed version control system that integrates tightly with Windows Explorer (and other platforms via file managers). It makes everyday Mercurial tasks faster and more visual, which is especially helpful for developers who prefer GUI tools or who need to inspect history, branches, and changesets quickly. This article gathers practical tips and tricks to help you speed up your workflow, avoid common pitfalls, and take advantage of lesser-known features.

1. Configure TortoiseHg for productivity

• Use global and repository-specific hgrc settings. Configure common options (username, email, extensions) in your global Mercurial config (~/.hgrc on Unix, Mercurial.ini on Windows) and put repo-specific settings in .hg/hgrc. This keeps consistent identity and shared extensions across projects while allowing per-project overrides.

• Enable useful extensions. Some essential extensions:

  • mq — patch queue (if you use patch-based workflows).
  • histedit — interactive history editing.
  • rebase — move changesets onto a new base (useful for cleaning history).
  • evolve / changeset evolution — safer history rewriting (requires server support or team agreement).
  • color — colored output in the command line. Enable extensions by adding them under the [extensions] section of your config.

• Set sensible defaults for diffs and merges. Under [ui] and [merge], configure the diff tool and merge tool you prefer (TortoiseHg ships with a merge tool integration, but you can set Beyond Compare, KDiff3, Meld, etc.). Example:

  [merge] tool = kdiff3 

  This reduces friction when resolving conflicts.

2. Heavy use of the Workbench (hg view)

The TortoiseHg Workbench is the central GUI for visualizing history, branches, and changesets.

• Keyboard shortcuts save time. Learn the basics:

  • Ctrl+T: Commit dialog.
  • Ctrl+P: Push.
  • Ctrl+L: Pull.
  • Space/Enter: open selected changeset.
  • Ctrl+F: search. Shortcuts vary by platform — check the Help menu.

• Use the graph visualization effectively. The graph view makes branch and merge topology obvious. Use mouse hover to preview changeset details; use right-click on nodes to perform common actions (update, graft, merge).

• Filter and search commits. Use the revision set language (revsets) at the top to narrow displayed commits. Examples:

  • author(“alice”) — commits by Alice
  • branch(“default”) and date(“last 30 days”) — recent commits on default
  • tag(“v1.0”):: — range since tag v1.0 Learning revsets pays off massively for complex histories.

3. Commit best practices inside TortoiseHg

• Write clear commit messages. The commit dialog supports multi-line messages and templates. Use the first line as a short summary (50–72 chars), leave a blank line, then add details. This keeps history readable.

• Stage changes selectively. TortoiseHg’s commit dialog lets you choose which files and even which hunks to commit. Commit related changes together; avoid monolithic commits that mix unrelated concerns.

• Use the “amend” feature for small fixes. If you forgot to include a file or need to tweak the message, use amend to update the latest commit rather than creating a follow-up commit. Be cautious when amending already-pushed commits.

4. Efficient branching and merging

• Prefer named branches for long-lived work; bookmarks for lightweight branching.

  • Named branches are permanent in history and useful for long-term, visible lines of development.
  • Bookmarks act like lightweight movable pointers (similar to Git branches); they’re easier for feature work when you don’t want permanent branch names.

• Use graft and rebase strategically.

  • Graft applies individual changesets onto another head.
  • Rebase moves a range of changesets onto a new base. Rebase keeps history linear but rewrites history — coordinate with your team.

• Use the merge tool proactively. When conflicts arise, open the merge dialog, inspect differences, and use a 3-way merge tool. TortoiseHg’s built-in visual merge is solid; external tools sometimes make resolving complex conflicts faster.

5. History rewriting and cleanup

• Understand the consequences of rewriting history. Commands like strip, histedit, rebase, and mq can rewrite history. Never rewrite public/shared history unless the team agrees.

• Use histedit for tidy commits before publishing. Histedit lets you reorder, squash, edit messages, or drop commits. It’s great for cleaning up a feature branch before pushing.

• Evolve for safer rewriting. The evolve extension (changeset evolution) provides a safer model for rewriting by tracking obsolescence and successors, making collaboration easier when rewriting is necessary.

6. Automation and hooks

• Use hooks for consistency checks. Pre-commit or pre-push hooks can enforce linting, run tests, or block accidental pushes. Configure hooks in hgrc:

  [hooks] pretxncommit = python:/path/to/your/hook.py:run 

  Hooks help catch issues early.

• Automate repetitive tasks with macros or scripts. TortoiseHg integrates well with shell scripts or batch files. Use them to automate builds, changelog generation, or deployment steps tied to repository actions.

7. Advanced features and lesser-known tricks

• Shelve and unshelve. Temporarily stash changes you’re not ready to commit. Shelving is safer than leaving dirty working copies and easier to manage than temporary branches.

• Use ‘record’ style committing interactively. The visual commit dialog lets you select hunks; this is like hg record and is great for producing atomic commits.

• Compare arbitrary revisions. Right-click two revisions in the Workbench graph and choose “diff revisions” to see exactly what changed between them — invaluable for code reviews.

• Export patches and email them. Use export/patch features to generate .patch files for review or to send via email — compatible with workflows that prefer patch exchange.

8. Performance tips for large repos

• Use shallow-ish clones for massive repos where possible. Mercurial supports cloning subsets via narrow or partial clone extensions; investigate them if clone/update is slow.

• Prune unnecessary history. If you control the repo and have agreed procedures, consider converting or archiving old history to keep active repositories lean.

• Optimize file system interactions. On Windows, exclude repositories from antivirus real-time scanning and use fast storage when possible; Mercurial performance is sensitive to I/O.

9. Collaborating with others

• Agree on a branching model and policies. Document whether teams use bookmarks, named branches, or an integration branch. Clarify when history can be rewritten.

• Use pull request / review workflows with hg review tools. Integrate Mercurial with code review systems (e.g., Phabricator, Review Board, or Bitbucket Mercurial support where available) so code is reviewed before merging.

• Communicate changes when rewriting. If you must rebase or strip shared history, tell collaborators and provide steps for them to rebase or recreate their work against the new history.

10. Useful keyboard and UI shortcuts (selective)

• Ctrl+T — Commit
• Ctrl+P — Push
• Ctrl+L — Pull
• Space/Enter — Open changeset
• Ctrl+F — Search (Check Help menu for a complete list and platform differences.)

Example workflows

• Feature branch with bookmarks:

  1. hg bookmark feature-x
  2. Work and commit locally in small steps (select hunks).
  3. Use histedit to tidy commits.
  4. Push bookmarks and open review.

• Quick bugfix directly on default:

  1. Update to default.
  2. Make minimal focused commit.
  3. Push and create a tag for release if needed.

Conclusion

TortoiseHg blends Mercurial’s powerful DVCS features with a user-friendly GUI. Become fluent with the Workbench, learn revsets and shortcuts, enable and configure helpful extensions, and adopt disciplined commit and branching habits. Those practices will make your Mercurial workflow faster, clearer, and more collaborative.