Welcome to TortoiseHg’s documentation!¶

Preface¶

Audience¶

This book is written for computer literate folk who want to use Mercurial to manage their data, but are uncomfortable using the command line client to do so. Since TortoiseHg is a Windows shell extension it’s assumed that the user is familiar with the Windows explorer and knows how to use it.

You can find the most up to date version of this documentation at our web site.

Reading guide¶

This Preface explains a little about the TortoiseHg project, the community of people who work on it, and the licensing conditions for using it and distributing it.

The Introduction explains what TortoiseHg is, what it does, where it comes from and the basics for installing it on your PC.

A Quick Start Guide to TortoiseHg is a quick tutorial on how to start with TortoiseHg.

TortoiseHg in daily use is the main chapter, it describes the frequently used components of TortoiseHg.

Settings describes how to configure TortoiseHg.

Use with other VCS systems describes how to use TortoiseHg as a client for non-Mercurial servers.

Frequently Asked Questions has a list of common questions and their answers.

Debugging describes how to debug any problems that you find.

TortoiseHg is free!¶

TortoiseHg is released under GPLv2. You are free to install it on as many computers as you like, and to redistribute it according to the GPLv2 license.

Community¶

Mailing List:

`Developers <thg-dev@googlegroups.com>`_ - Patches, bug reports, development discussions.

And our wiki on Bitbucket.

Acknowledgements¶

Thanks to the many people who contribute to the TortoiseHg project. It takes a community of developers, translators, and users to build a truly useful tool (especially users who care enough to report bugs and file feature requests).

The TortoiseHg installer for Windows includes the TortoiseOverlays handler, as provided by the TortoiseSVN project.

The history viewer of TortoiseHg is based on hgview, a tool developed by David Douard and others, with the financial support of Logilab.

Conventions used in this manual¶

The following typographical conventions are used in this manual:

Ctrl-A: Indicates a key, or combination of keys, to press.
Commit: Indicates a label, button or anything that appears in user interfaces.
TortoiseHg… ‣ About: Indicates a menu choice, or a combination of menu choice, tab selection and GUI label. For example TortoiseHg… ‣ Global settings ‣ Commit ‣ User name means do something in User name label under Commit tab selectable from the menu choice TortoiseHg… ‣ Global settings.
.hg/hgrc: Indicates a filename or directory name.
thg log: Indicates a command to enter into command window.
myproxy:8000: Indicates a text to enter into a text input field in the GUI.

Note

This is a note.

Warning

An important note. Pay attention.

Introduction¶

What is TortoiseHg?¶

TortoiseHg is a set of graphical tools and a shell extension for the Mercurial distributed revision control system.

Note

hg is the symbol for the chemical element Mercury

On Windows,: TortoiseHg consists of the Workbench graphical application, a shell extension which provides overlay icons and context menus in your file explorer, and a command line program named thg.exe which can launch the TortoiseHg tools. Binary packages of TortoiseHg for Windows come with Mercurial and a merge tool and are thus completely ready for use “Out of the Box”.
On Linux,: TortoiseHg consists of a command line thg script and a Nautilus extension which provides overlays and context menus in your file explorer. You must have Mercurial installed separately in order to run TortoiseHg on Linux. TortoiseHg binary packages list Mercurial as a dependency, so it is usually installed for you automatically.

Note

On Windows, TortoiseHg includes both thg.exe and thgw.exe. The latter is intended to be launched from desktop shortcuts or menu entries as it will refuse to open a command console. thg.exe is for use on the console, and can provide command line help. The thg.cmd batch file that our installer adds into your PATH runs thg.exe.

TortoiseHg is primarily written in Python and PyQt (the Windows shell extension being the notable exception). The thg script and TortoiseHg dialogs can be used on any platform that supports PyQt, including Mac OS X.

Installing TortoiseHg¶

On Windows¶

TortoiseHg comes with an easy to use MSI installer. You can always find the most up to date release on our website. Simply double click on the installer file and follow its instructions.

After a first time install, a re-login is usually required to start the icon overlays.

During upgrades, the installer will ask to close or restart any applications that have loaded the TortoiseHg shell extension. If you allow those applications to be closed, the upgrade will not require a reboot or logout. If other users are logged in, or if there are applications which cannot be shutdown, a reboot will be required to complete the install.

Note

If you have a legacy version of TortoiseHg installed, the installer will require that you to remove it. The uninstall can be initiated from the control panel or the start menu.

Warning

Legacy uninstallers (<=0.9.3) have a tendency to delete your user Mercurial.ini file, so backup your file before uninstalling the older TortoiseHg versions. This is not a problem with the newer MSI packages.

Legacy TortoiseHg installers (prior to version 1.0) were built with InnoSetup. They installed a TortoiseOverlay package as a separate application, so you always saw both TortoiseHg and TortoiseOverlay as two applications in the Add/Remove Programs control panel program. (On x64 platforms, there were two TortoiseOverlays, one for x86 processes and one of x64 processes).

The new MSI installers for TortoiseHg include the TortoiseOverlay packages as “merge modules” so they do not appear as separate applications anymore. It should be safe to uninstall the older TortoiseOverlay applications from Add/Remove Programs after you uninstalled the legacy (<=0.9.3) TortoiseHg installer, unless you have other Tortoise products that still use the separate TortoiseOverlay MSI approach (TortoiseCVS or TortoiseBZR).

Note

TortoiseOverlay is a shim package that allows multiple Tortoise style shell extension clients to share overlay slots. This is necessary because even modern Windows platforms only support a limited number of overlay slots (11-14). TortoiseOverlay packages are created by the TortoiseSVN developers.

To be completely safe, there are two approaches you can take:

Just leave the old TortoiseOverlay packages installed. They do not harm anything.
Uninstall all the old TortoiseOverlay packages, then re-install all of your Tortoise products until they are all functional.

Finally, if you have problems with the shell extension even after re-logging in, we recommend you re-run the installer and select the Repair option. There were problems with a few versions of TortoiseOverlay that cause upgrades to subtly fail until the Repair process is run.

Language settings¶

The TortoiseHg user interface has been translated into many languages. Language packs are not required since all available languages are installed by default. You can select your preferred UI Language in the global settings tool.

The Windows shell extension context menus get their translations from the Windows registry. Translations for many locales were installed under C:\Program Files\TortoiseHg\i18n\cmenu. Select the locale you would like to use, double-click on it, and confirm all requests.

On Linux and Mac¶

The most recent Linux packages can be found on our download page.

For Mac OS X, no packages are available but you can run thg and all the dialogs via the source install method. For details, see Mac OS X.

Note

If you install TortoiseHg from source, you need to add our contrib/mergetools.rc file to your HGRC path in some way. One approach is to %include it from your ~/.hgrc file.

What’s New¶

TortoiseHg 2.0¶

Philosophy¶

The following philosophical changes were made between TortoiseHg 1.0 and TortoiseHg 2.0.

Workbench¶

We wanted a single ‘TortoiseHg’ application which can access nearly all TortoiseHg (and Mercurial) functionality and that could be launched by a desktop or start menu shortcut. So we developed the Workbench application.

The Workbench can support multiple repositories open at a time via “Repo Tabs” across the top of the main window.

Each repository tab supports multiple “Task Tabs” beneath its graph splitter. These task tabs are switchable via icons on the side of the Workbench or via application menus. Available task tabs include a changeset browser, a commit tool, a history search widget, and a sync widget.

Also available are two dockable widgets - a Repository Registry which lists all known repositories on your local machine and an Output Log Window which displays running command lines and their output and can also function as a minimal shell.

Showing Mercurial command lines¶

In an effort to educate users on Mercurial’s command interface, nearly all commands are executed in the log window, displaying the full command line and Mercurial’s output (progress indication is provided by progress bars inside the Workbench status bar). The few tools that do not use a command log window will generally display the command line they execute.

Resolve tool, deliberate merges¶

TortoiseHg 2.0 introduces a resolve dialog for resolving conflicted file merges. It shows the users all the files that require resolution and those files that have been resolved, allowing merges to be verified.

As supported by Mercurial’s resolve command, individual file merges may be restarted as many times as necessary to get the merge correctly completed.

By default, TortoiseHg will use the resolve dialog to resolve all conflicts, including trivial conflicts. It instructs Mercurial to never merge files automatically, deferring their resolution until the resolve dialog can be launched. This is true for merges, update commands that require content merges, rebases, and backouts.

Shelve Improved¶

TortoiseHg 2.0 includes a new shelve tool which is capable of moving changes between your working directory, a shelf file, or an unapplied MQ patch.

Revision Sets¶

We have replaced the filter bar of the Repository Explorer with a revision set bar in the Workbench. Revision sets were introduced in Mercurial 1.6 and have been integrated with an increasing number of commands in each subsequent release. They are a powerful query language for finding and specifying revisions in your repository.

The Workbench also includes a revision set editor which both teaches the user the available keywords and their arguments, and offers brace matching, auto-completions, and other editing amenities.

In TortoiseHg 2.0, incoming and outgoing changesets are visualized as revision sets. In previous versions they were represented by graph annotations.

Technology¶

Qt and PyQt¶

TortoiseHg 2.0 has been a near rewrite of all of the tools and dialogs taking advantage of Digia’s excellent Qt UI framework and Riverbank Computing’s fine PyQt Python bindings.

QScintilla2¶

TortoiseHg uses the QScintilla2 editing component extensively to:

display file contents and diffs with syntax highlighting
display annotations with syntax highlighting
edit commit messages with auto-completion of filenames and source symbols
edit revision set strings with brace matching and auto-completion

One can configure the QScintilla2 tab stop parameter using the settings tool, while white space visibility and wrap are controlled by context menus.

Polling of repository state and config¶

The Workbench and other applications like the commit tool will poll repositories on your local machine to detect changes made to either the repository or their configuration files, and automatically update running applications as necessary. Nearly all configuration changes are effective immediately, with the notable exception of enabling or disabling Mercurial extensions. Changes to extension configuration generally require application restarts before they take effect.

Immediate bug report dialogs¶

Prior to TortoiseHg 2.0, bug reports were written to stderr as they occured and stderr was captured and scanned at exit to report those errors to the user. While we gained many valuable bug reports via this mechanism, there was rarely any context on what operations caused these bugs.

In TortoiseHg 2.0, we have created a generic exception handler that catches all Python exceptions that are otherwise unhandled by application code. This allows us to display exception tracebacks almost immediately after they occur (after a short timeout to collect consecutive exceptions together). The hope is that future bug reports will contain better reproduction instructions, or at least context for the tracebacks.

Demand loaded graph¶

To keep refreshes as efficient as possible, the graphing algorithm will only load a couple hundred revisions initially during a refresh, and then load further revisions only when those revisions are required to be displayed. You will notice scrolling through the graph is jerky, these are bulk loads of revisions into the graph. To avoid this jerkiness you can force TortoiseHg to load all revisions in the graph via the Load all revisions option from the View menu.

A Quick Start Guide to TortoiseHg¶

Welcome to TortoiseHg and the Mercurial! TortoiseHg is a set of graphical applications and Windows Explorer shell extension that serve as a friendly front-end to the Mercurial distributed version control system (DVCS).

All TortoiseHg functionality is reachable from 3 places:

The Workbench application

You can start the Workbench from the Start Menu, or by right clicking on the Desktop and selecting Hg Workbench.

Start the Workbench from the Desktop
The Explorer context menu

All you have to do is right click on the right folder or files in Explorer, and select a context menu entry.
The thg command line application

Type the appropriate commands from any command line interface, in the form thg <command> [options].

In this quick guide we would like to make you get started using the Workbench application, but we will also indicate how to do the same with the other possibilities.

Mercurial commands are also available from the standard hg command line application.

Configuring TortoiseHg¶

Your first step should be to make sure that you are correctly identified to TortoiseHg. You do this by opening the global settings dialog.

Workbench: select File ‣ Settings… from the menu

Explorer: choose TortoiseHg ‣ Global Settings from the context menu

Command line: type thg userconfig

This opens the TortoiseHg settings dialog, editing your global (user) configuration.

TortoiseHg Settings Dialog

First select the Commit page and enter a name in the Username field.

Note

If you neglect to configure a username TortoiseHg will ask you to enter one when you try to commit, which is the first time a username is actually required.

Note

There are no hard fast rules on how to format your username, the field is free form, but the following convention is commonly used:

FullName <email>

for example

Donald Duck <donaldduck@example.net>

The email address is stripped when viewing history in the revision history viewer, and the built-in web server obfuscates email addresses to prevent SPAM.

Next, select the TortoiseHg page and select the Three-way Merge Tool entry. In the drop down list you will find all of the merge tools detected on your computer (kdiff3 is provided by the Windows installer) and a number of internal merge behaviors. Select your preferred merge tool.

If you prefer for TortoiseHg to also use your selected merge tool for visual diffs, you can leave the Visual Diff Tool unspecified. Otherwise, select your favorite visual diff tool from the drop down list of detected visual diff tools.

If there are no options in either drop-down list, you must install a diff/merge tool that is supported by our mergetools.rc or configure your own tool.

Note

If you installed TortoiseHg from source, you need to add our contrib/mergetools.ini file to your HGRC path in some way. One approach is to %include it from your ~/.hgrc file.

Feel free to configure other global settings while you have the dialog open. You will have the chance later to override these global settings with repository local settings, if required.

Click the OK button to save the changes you have made and close the settings dialog.

Note

Most TortoiseHg settings changes are noticed immediately, but loading or unloading extensions usually requires restarting all open applications for the changes to take effect.

Getting Acquainted¶

Mercurial supports many different collaboration models. This chapter describes just one of those models: a single central repository. The central repository model does not scale as well as other models, but it is the most familiar to those coming from other revision tools and thus is the most common approach people start with.

To get started, suppose you volunteer to create the central repository. There are ways to convert non-Mercurial repositories into Mercurial repositories, but this example assumes you are starting from scratch.

Initialize the repository¶

Create the initial repository on your local machine:

Workbench: select File ‣ New Repository… from the menu

Explorer: select TortoiseHg ‣ Create Repository Here from the context menu

Command line: type thg init

You can do this from within the folder you want to create the repository in, or enter the correct path in the dialog. You only need to do this once in the root folder of your project.

Repository Init Dialog

We suggest you keep Create special files (.hgignore, …) checked, and do not check Make repo compatible with Mercurial < 1.7, unless you have a strong reason to do so.

After pressing Create, Mercurial creates a subdirectory in your project folder named .hg. This is where Mercurial keeps all its version data. It is called the repository or store, while the directory containing the source files is called the working directory. You never need to specify the .hg directory when running commands, you only need to specify the working directory root. It is mentioned here just so you better understand how Mercurial works.

The new repository will also be added to the RepoRegistry when you perform this operation from the Workbench.

Warning

It is dangerous to manually edit the files in .hg directory, repository corruption can occur. .hg/hgrc is perhaps the only exception to this rule.

Note

Perhaps you already created one or more repositories. As you can manage multiple repositories in the Workbench at the same time, you can add these existing repositories by selecting File ‣ Open Repository… from its menu, and selecting their folder. Or you could drag their folder from Explorer into the RepoRegistry pane.

Add files¶

Now it’s time to tell Mercurial which files must be tracked. There are various ways to do this:

Workbench: goto the Commit task tab, rightclick on the file, and select Add from the context menu. This will change the status indication of that file into ‘A’ and the filename will turn green.
Explorer: select TortoiseHg ‣ Add Files… in the context menu. A dialog will open for you to check the selected files and accept the add operation. You can also open the status tool by selecting TortoiseHg ‣ View File Status. Check the files you want to add and select Add from the file context menu.
Command line: type thg status
Or skip adding new files as a separate step and have the commit tool add them implicitly. The commit tool is very similar to the status tool and allows you to do all of the same tasks. In this tool you can add and commit an untracked file by just checking the file and pressing Commit.

Ignore files¶

You may have some files in the foldertree of your repository that you don’t want to track. These can be intermediate results from builds f.i. that you do not wish to always delete immediately, or files your editor generates, etc. You can mark these files as ignored in some different ways too.

Workbench: goto the Commit task tab, rightclick on the file, and select Ignore… from the context menu to open the ignore filter dialog.
Explorer: select TortoiseHg ‣ Edit Ignore Filter.
Command line: type thg hgignore to bring up the ignore filter dialog.
You can also launch the ignore filter from the status tool (the menu option is named Ignore).

Choose a file from the list or manually type in a Glob or Regular expression filter and then press Add. Changes to the ignore filter take effect immediately.

Note

The .hgignore file, contained in the working directory root, is typically tracked (checked in).

Note

It is good practice to not have many unknown files in your working directory, as it makes it too easy to forget to add vital new files. It is recommended that you keep your .hgignore file up to date.

Commit¶

Commit your local repository now:

Workbench: click on the Working Directory revision which also selects the Commit task tab, or directly select the Commit task tab

Explorer: right-clicking anywhere in the folder, or on the folder itself, and then selecting Hg Commit…

Command line: type thg commit

Write a commit message, select the files you wish to commit, then press Commit. Your previous commit message will be in the message history drop-down, so you do not have to type it in again from scratch.

Commit Tool

Fetching from the group repository¶

You want to start collaborating with your team. They tell you something like fetch the repository from x. What does that mean? It means that you want to make a copy of the repository located at x on your local machine. Mercurial calls this cloning and TortoiseHg has a dialog for it.

Workbench: select File ‣ Clone Repository… from the menu

Explorer: select TortoiseHg ‣ Clone… from the context menu

Command line: type thg clone

Then enter the destination path, and click OK.

Clone Dialog

This time you do want to update the working directory because you want to work on the project, under Options uncheck Do not update the new working directory so Mercurial updates the working directory with the tip revision in your new clone.

Working with your repository¶

Suppose you’ve introduced some changes. It is easy to discover what pending changes there are in the repository.

Workbench: go to the Commit task tab and inspect the filelist at the left

Any files marked with ‘A’ (added, green), with ‘?’ (unversioned but not ignored, fuchsia), with ‘M’ (modified, blue), or with ‘!’ (removed, red) indicate pending changes that should be committed.

The Commit task tab in the Workbench gives you a way to see differences within the files, or you can use your visual difference tool (kdiff3). Mercurial allows you to commit many changes before you decide to synchronize (share changes) with the group repository.

Explorer: inspect the icons on the folders and files in your repository

Folders or files in Explorer marked with one of the icons below are another way of indicating pending changes. You can traverse the directories to find specific changes and commit them from Explorer. Though it might be quicker to do that from the Commit task tab in the Workbench.

Overlay Icons on Vista

Command line: type thg commit

When you’re ready to publish your changes, you

Commit your changes to your local repository (see above).
Pull changes from the group repository into your repository using TortoiseHg ‣ Workbench or thg log, select the Sync task tab, choose the path to the group repository in the syncbar and then click the Pull button.
If some changesets were pulled, merge those changes with your local changes and then commit the merge into your local repository. From the revision history viewer (TortoiseHg ‣ Workbench or thg log) open the context menu over the changeset which you want to merge and select Merge with local…. Finally, in the merge dialog, press Merge and then Commit.
Ensure your merged work still builds and passes your extensive test suite.
Push your changes to the group repository, TortoiseHg ‣ Workbench or thg log, select the path to group repository and then click the Push button.

Which may sound complicated, but is easier than it sounds.

Note

Merges can be safely restarted if necessary.

Mercurial makes collaboration easy, fast, and productive. Learn more at Mercurial’s wiki.

TortoiseHg in daily use¶

Common Features¶

These features are common to many TortoiseHg tools, so we document them here just once.

Visual Diffs¶

Visual Diff Window

In TortoiseHg 1.0, the visual (external) diff infrastructure was refactored. The new system uses tool descriptions in mergetools.rc to detect most common diff tools on your computer (including KDiff3, which ships in our installer) and select the best available tool.

If the user has selected a merge tool (TortoiseHg ‣ Three-way Merge Tool), that tool will also be used to perform visual diffs, bypassing the tool selection process. However the user can still select a separate tool (TortoiseHg ‣ Visual Diff Tool) for visual diffs if they chose.

The merge tool configuration file contains optimal command lines for each tool, so no further configuration is required by the user. They only need to select the tools they wish use, or accept the defaults.

The visual diff system will use any existing extdiff configuration it finds. Since extdiff did not support three way diff arguments until very recently and still does not support label arguments, you will likely have a better experience by disabling or deleting any extdiff configuration you may have.

The visual diff system will directly use the selected diff tool unless the action you are attempting requires the use of the TortoiseHg visual diff window. The list of conditions includes:

The selection of files being compared require multiple tools
The selected tool forks detached background processes
The selected tool does not support the required directory diffs
The selected tool does not support three way comparisons
The file changes include renames or copies

When the visual diff window is used, the temporary files are cleaned up when the dialog is closed. Thus it should be left open until you close all of your diff tool instances. When your diff tool is launched directly, the temporary files are deleted when your tool exits.

If your diff tool is launched directly to compare a working copy file, it will directly diff against the working file so you may modify it from within the diff tool. If you are comparing multiple files, the visual diff system will make a snapshot of the working copy files and track their initial sizes and timestamps. When your diff tool exits, the system compares the sizes and timestamps and copies modified files back over the original working copies. In this way, you can still modify your working copy files from your visual diff tool even when performing directory comparisons.

When the visual diff window is used to compare working copy files, it always directly diffs against the working copy files since it always operates on a single file at a time.

Deprecated since version 1.0: The TortoiseHg ‣ Skip Diff Window configurable has been removed because it is now redundant.

Adding Tools¶

If you have a visual diff tool installed that is not supported by TortoiseHg, you can create a tool configuration for it in your user Mercurial.ini file. See Mercurial’s documentation on how to configure your tool for use in file merges. When that is complete, you can add the extra keys used by TortoiseHg for visual diff:

diffargs:  the arguments to use for two-way file comparisons
diff3args: the arguments to use for three-way file comparisons
dirdiff:   this tool supports two-way directory comparisons
dir3diff:  this tool supports three-way directory comparisons

When building command line arguments, you can use the following variables:

$parent1:  the file or directory from the first parent revision
$parent2:  the file or directory from the second parent revision
$child:    the file or directory from the revision being compared
$parent:   a synonym for $parent1

$plabel1:  a symbolic name for the first parent revision
$plabel2:  a symbolic name for the second parent revision
$clabel:   a symbolic name for the revision being compared

Obviously, $parent2 and $ancestor are only meaningful when used in three way diff arguments, for viewing merge changesets. If your diff tool cannot use the ancestor revision in any productive way, it is safe to leave it out of the diff3args command line.

Note

On Windows, the executable parameter can use environment variables using the syntax ${ProgramFiles}

If unconfigured, the default value of diffargs is ‘$parent $child’. The default value of diff3args is “”, indicating the visual diff tool cannot perform three way comparisons.

If you create a new visual diff tool configuration, or improve upon an existing configuration, please email it to our development mailing list so it may be incorporated in a future release.

Word Diffs¶

The TortoiseHg Windows installers now include TortoiseSVN’s scripts for comparing (and sometimes merging) many binary document formats. These are configured in the site-wide mergepatterns.rc as handlers for each binary format’s common file extensions, so no user intervention is required.

In order to support file extension based tool selection, TortoiseHg has added support for a [diff-patterns] section equivalent to Mercurial’s merge-patterns section.

Windows Explorer Integration¶

Context Menus¶

TortoiseHg commands may be accessed via the context menu of Explorer windows and other applications which use the standard File/Open dialogs. Here is the context menu for a revisioned folder:

Context menu for a folder under Mercurial revision control

And here is the context menu for selected files or folders:

Context menu for file or folder selection

TortoiseHg provides dialogs for the most regularly used Mercurial commands. Less frequently used and newly added Mercurial commands may be accessed from the CLI (command line interface) through cmd.exe on Windows.

Overlay Icons¶

TortoiseHg provides visual representation of the file status via overlay icons in the MS-Explorer windows. This is similar to those that found on other Tortoise client, such as TortoiseCVS and TortoiseSVN.

TortoiseHg shares the overlay icons with TortoiseSVN (version 1.5.x or later) and the other “Tortoise” projects via the use of TortoiseOverlays (another project created by TortoiseSVN team).

Overlay icons in Icons view (XP)

The context menu has an Update Icons option which forces TortoiseHg to refresh the icons in the currently browsed repository or directory of repositories. The taskbar icon will turn green and the directory icons will turn into question marks while this refresh is in progress.

Shell Configuration¶

The overlay handler and context menus are configurable. From any folder background (even the desktop), right click and select TortoiseHg ‣ Explorer Extension Settings. This opens the Explorer Extension Settings dialog.

On the tab “Context Menu” you can promote individual menu options to the top level menu.

Explorer Extension Settings Dialog, Context Menu tab

On the “Icons” tab you configure settings related to the overlay icons and the icon of the “Overlay Icons Server” in the taskbar (in the notification area of Windows).

Explorer Extension Settings Dialog, Icons tab

Enable overlays:: If checked, overlay icons are shown on folders and files in the working directory (woking copy) of Mercurial repositories. (Default: checked)
Local disks only:: If checked, overlay icons are only shown for volumes on local disks, not on network shares. Scanning for Mercurial repositories over the network may result in high latency in the user interface of explorer. Check this option if browsing network shares becomes too slow and/or you do not need overlay icons on non-local volumes. (Default: not checked)
Enabled Overlay Handlers:: These (per user) settings provide the possibility to disable overlay icon handlers in the shared TortoiseOverlays component. The TortoiseOverlays component is shared by all Tortoises (TortoiseHg, TortoiseSVN, etc), with the goal to avoid registering too many icon slots, by using a common set of icons slots for all Tortoises (thus using the same set of icons for all Tortoises). The total number of overlay slots available on Windows is fairly limited and depends on the exact Windows version. For example, on a pristine install of Windows 7, there are only 8 free overlay handler slots available. This section allows to disable certain non-essential overlay handlers, to reduce icon handler slot consumption by the TortoiseOverlays component. Unchecking handlers in this section increases the chances that important handlers like “Normal” (green checkmark) or “Modifed” (red exclamation mark) will still get an icon slot, even if there are too many handlers registered on a computer. Unchecking handlers that are not used by TortoiseHg (that is: Locked, Readonly, Ignored, Deleted) is highly recommended, if you know that no other Tortoises (e.g. TortoiseSVN) uses them. Make sure the “Added” and “Unversioned” handlers are enabled, as these are used by TortoiseHg. (Default: all checked)

Warning

The “Enabled Overlay Handlers” settings affect all Tortoises for a user. A logoff/login is required to make changes in that section effective.

Taskbar:: Checkmark “Show Icon” to show the icon of the Overlay Icon Server in the taskbar in the notification area. “Highlight Icon” highlights that icon using a light green color while the icon server is busy updating cache files in the repository (files .hg\dirstate and .hg\thgstatus). (Default: both checked)

One can selectively disable overlay icons in a specific repository by editing the .hg\thgstatus file inside the repository and replacing its contents with a single line containing:

@@noicons

GNOME desktop integration¶

TortoiseHg also provides shell integration with the GNOME desktop via a nautilus-python plugin. If you have installed TortoiseHg from a distribution package, the odds are that this extension is already configured. If not, please consult our Wiki for instructions on how to enable this feature.

While the nautilus extension does not have its own GUI for managing the overlays and context menus, it does support command promotion into the top menu. It requires you to edit your ~/.hgrc file and add lines like these:

[tortoisehg]
promoteditems = commit, log, synch

GNOME/Nautilus screenshot

While convenient in most cases, the overlay feature can cause slowdowns on big repositories. To disable overlays, edit your ~/.hgrc file and add:

[tortoisehg]
overlayicons = false

Workbench¶

The Workbench is the primary TortoiseHg application. It allows you to browse your local repositories, make commits, perform searches, synchronize with other repositories, and perform various maintenance tasks. Nearly every Mercurial feature is accessible from the Workbench.

Workbench dialog.

Workbench Main Widgets are:

Revision History View

A tabbed widget to view multiple repositories at once. The different columns show general information about each changeset in the graphlog. You can configure the columns to show from the menu via View ‣ Choose Log Columns…, and there you can reorder the columns too. This is the main or central widget of the Workbench application.

Repository Registry

This widget, by default shown on the left, allows to manage multiple repositories from the Workbench. You can show/hide it via View ‣ Show Repo Registry or with the corresponding button in the Dock Toolbar. It’s also a dockable widget. The View ‣ Show Paths menu option allows to not only view the names of the repositories but also their path in a second column.

Output Log

This dockable widget, which can be shown/hidden with View ‣ Show Output Log, gives the user information about the Mercurial commands that were executed during the current session. You can also use it as a commandline by typing Mercurial commands at its prompt directly. It shows any error messages when appropriate. Content is wiped when the Workbench is closed.

Task Tabs

The lower right part of the Workbench is occupied by a stack of widget where you can perform various frequent tasks. It is a tabbed widget. See further for more detail about each one.

Workbench Menus¶

The Workbench has a menu bar for accessing tool functions and for launching other tools.

File

Handle repositories and settings.

File Menu

View

Manage the visibility of various parts of the Workbench.

View menu

Repository

Perform special actions on the active repository.

Repository menu

Help

About shows TortoiseHg version info.

Revision Graph Details¶

The graph column shows the child-parent relationships between revisions in your repository history. This column auto-sizes for as many lines of ancestry that are required to visualize the revisions you have loaded. The column has an initial hard-limit width to prevent some degenerative cases from breaking the viewer, but can be resized after refreshes.

Performance Implications¶

There are some Workbench features that could have performance implications in large repositories.

View ‣ Choose Log columns…

Enabling the Changes column can be expensive to calculate on repositories with large working copies, causing both refreshes and scrolling to be slow.

View ‣ Load all

Normally, when the user scrolls through the history, chunks of changesets are read as you scroll. This menu choice allows you to have the Workbench read all the changesets from the repository, probably allowing smoother moving through the history.

Revision Context Menus¶

Right-clicking on revisions in the graph pane brings up a different context menu when one, two, or more revisions are selected. Context menus can also differ according to the type of revision(s) (working dir, regular revision, (un)applied mq patch). Here we give a list of all existing context menu entries.

Right-clicking on a selection of revisions in the (top) graph pane will bring up the revision context menu.

With only one revision selected:

Update…

Update your working directory to this revision. Opens the TortoiseHg update dialog with this revision selected.

Diff to Parent

Open this change in your visual diff tool.

Diff to Local

Display changes (visual diff) between this revision and your current working directory.

Browse at Revision

Brings up the Manifest window with the content of all files in the repo at the selected revision.

Similar Revisions…

Open the TortoiseHg dialog to search for similar revisions.

Merge with local…

Merge the selected changeset with the Working Dir. Opens the TortoiseHg merge dialog with this revision selected.

Tag…

Allows to manage tags to the selected revision.

Bookmark…

Allows to manage bookmarks for the selected revision.

Backout…

Create a backout changeset for selected revision.

Copy Hash

Copies the revision hash to the clipboard. Copy current revision’s full hash to the clipboard.

Under X11, the short changeset hash is automatically copied to the primary selection when the revision is clicked, you paste it by pressing the middle mouse button.

Export

Export Patch…: Generate a patch file containing this revision’s changes.
Email Patch…: Send this revision’s changes to email recipient. Opens the TortoiseHg email dialog with this revision selected.
Archive…: Open the archive dialog for this revision, allowing user to generate a backup copy of the repository at that revision.
Bundle Rev and Descendants…: Open a dialog for exporting this revision and its descendants to a bundle file.
Copy Patch: Copies this revision’s changes to the clipboard. Only visible when MQ is enabled.

Change Phase to

public: Change the phase of this revision to public.
draft: Change the phase of this revision to draft.
secret: Change the phase of this revision to secret.

Graft to Local…

Open the graft dialog to copy the selected revision.

Modify history

Unapply Patch: Pop patches upto this one Only visible when MQ is enabled
Import to MQ: Import selected revision into the current patch queue. Only valid for qbase or checked out head revision. Only visible when MQ is enabled
Finish patch: Transforms the MQ patch into a regular changeset. Only visible when MQ is enabled
Rename Patch…: Renames the MQ patch file. Only visible when MQ is enabled
MQ Options: Open the MQ options dialog. Only visible when MQ is enabled
Rebase…: Move the selected revision and all of its descendants onto the current working parent revision. Only visible when rebase is enabled
Prune…: Mark the selected revision as obsolete. Only visible when evolve is enabled
Strip…: Remove the selected revision and all of its descendants from the repository [1] Only visible when MQ is enabled

With two revisions selected:

Visual diff…: Open this change in your visual diff tool.
Export selected: Creates a patch file for each changeset in selected range.
Email selected…: Opens email dialog with range of changesets.
Export DAG range: Creates a patch file for each changeset in selected range.
Email DAG range…: Opens email dialog with range of changesets.
Bisect - Good, Bad…: todo See bisect section below.
Bisect - Bad, Good…: todo See bisect section below.
Compress history…: Brings up a dialog where you can compress the youngest changeset into the older one.

With more than two revisions selected:

Export selected: Creates a patch file for each changeset in selected range.
Email selected…: Opens email dialog with range of changesets.

[1]	The strip command will store the stripped revisions in a bundle file that can later be reapplied. See also EditingHistory.

File Context Menus¶

Right-clicking on filenames in the file list pane (bottom left of the RevDetails task tab) will bring up a context menu for the selected file:

Visual Diff

Open this revision of the file in your visual diff tool.

Visual Diff to Local

Visualize differences between this revision and your checked out version.

View at Revision

Open this revision of the file in your visual editor [2].

Edit Local

Open the checked out version of the file in your visual editor [2].

Revert to Revision

Checkout this specific revision of this file [4].

File History

Show revisions that modified this file [3].

Compare file revisions

Brings up a new dialog where you can compare any revision of the file with any other revision in the history.

[2]	(1, 2) Global Settings ‣ TortoiseHg ‣ Visual Editor

[3]	Does not show revisions where a file was deleted, as this is only a manifest change, it does not modify the file’s history.

[4]	The new contents will appear as local changes and must be committed.

Right-clicking on filenames in the file list pane of the Commit task tab will bring up a different context menu for the selected file:

Edit

Open this revision of the file in your visual diff tool.

Add

Add this file to the repository for versioning.

Detect Renames…

Brings up a dialog where you can try to detect renamed files.

Ignore

Adds the selected file to the .hgignore content.

Delete unversioned

Deletes unversioned files from disk.

Message Parsing¶

The changeset display pane will detect and underline changeset hashes, HTTP(s) URLs, and bug report identifiers inside changeset messages. These underlined phrases are clickable links.

Every word-boundary delimited string of 12 or 40 characters from the range [0-9a-f] is considered a changeset link. Clicking on it in the repository explorer will jump to the given changeset if possible.

HTTP and HTTPS URLs are similarly turned into clickable links which are opened in your default web browser.

Issue tracker links are enabled when configured in the tortoisehg section of your configuration files. Since only a single issue tracker can be configured at a time, it is typically configured in the repository’s .hg/hgrc file. There are two keys: issue.regex and issue.link. The first defines the regex to match when picking up issue numbers, while the second defines the command to run when an issue number is recognized.

You may include groups in issue.regex, and corresponding {n} tokens in issue.link (where n is a non-negative integer). {0} refers to the entire string matched by issue.regex, while {1} refers to the first group and so on. If no {n} tokens are found in issue.link, the entire matched string is appended instead.

Examples:

BitBucket:
issue.regex = #(\d+)\b
issue.link = https://bitbucket.org/<your project and repo>/issue/{1}/

Mercurial:
issue.regex = \bissue(\d+)\b
issue.link = https://bz.mercurial-scm.org/show_bug.cgi?id={1}

Output Log Console¶

The console built into the Workbench Output Log dock widget can run Mercurial (hg) commands, TortoiseHg (thg) commands, a couple special commands, and limited shell commands. Commands are always executed in the root of the current repository. The prompt is updated to keep you aware of the context.

If the command line begins with ‘hg’, the Mercurial command is run in TortoiseHg’s execution environment; meaning output is sent to the log widget and input requests are handled by dialog windows.

If the command line begins with ‘thg’, the requested command is run in a new window but in the same process. For instance ‘thg ci’ will open a new commit tool window for the current repository.

It the command is ‘clear’ (or ‘cls’), the output log contents are erased.

If the command is ‘exit’, the output log window is closed.

Otherwise, the command line is forwarded to your platform’s default command shell with a limited execution context. There is no stdin while stdout and stderr are piped to the output log.

Configurables¶

The Workbench has a few configurable options that can be set in the TortoiseHg Settings dialog on the Workbench tab.

Author coloring

If true, each author’s changeset will be given a unique color

Long Summary

Concatenate commit message lines until 80 chars are reached

Graph batch limit

Number of revisions to read in each batch load

Dead Branches

Comma separated list of branch names that should be ignored when building a list of branch names for a repository.

Branch Colors

Space separated list of branch names and colors on the form branch:#XXXXXX. Spaces and colons in the branch name must be escaped using a backslash (\). Likewise some other characters can be escaped in this way, e.g. \u0040 will be decoded to the @ character, and \n to a linefeed.

Hide Tags

Space separated list of tags that will not be shown. Useful example: Specify “qbase qparent qtip” to hide the standard tags inserted by the Mercurial Queues Extension.

The exact colors given to particular users can be configured by adding lines like these to your Mercurial.ini file:

[tortoisehg]
authorcolor.USERNAME = color

The Workbench also respects the following settings on the TortoiseHg tab:

Tab Width

Number of spaces to expand tabs in diffs

Max Diff Size

Maximum size of file to be diffed

From command line¶

The Workbench can be started from command line

thg log [OPTIONS] [FILE]

aliases: history, explorer, workbench

workbench application

use "thg -v help log" to show global options

Create a new repository¶

To create a new repository into an existing directory (project) you have to run the init dialog. From the explorer context menu select TortoiseHg… ‣ Create Repository Here over the directory, or, within the folder, type thg init.

Repository Init Dialog

Destination: Is the directory where the repository will be created. It is always filled with the current directory, so if you launch the dialog from the right directory there is no reason to change it.
Create special files (.hgignore, …): If selected TortoiseHg creates an empty .hgignore file in the working directory.
Make repo compatible with Mercurial <1.7: If selected TortoiseHg creates an older format Mercurial repository. Do not check unless you have a strong reason to do, and you know what you are doing.
Show in Workbench after init: When the repository was successfully created, it is added to the RepoRegistry, and opened in a new tab the Workbench.
Hg command: This field displays the command that will be executed by the dialog.

Creating a new repository means create a subdirectory called .hg. In this subdirectory Mercurial keeps all its versioning information.

Warning

It is dangerous to manually edit the files in .hg directory, repository corruption can occur. .hg/hgrc is perhaps the only exception to this rule.

From command line¶

The init tool can be started from command line

thg init

The syntax is

thg init [DEST]

where [DEST] is the path to destination folder.

Clone a repository¶

To clone a repository you have to run the clone dialog. From the explorer context menu select TortoiseHg… ‣ Clone a repository or type thg clone.

Clone Dialog

Source: It is the path (or URL) of the repository that will be cloned. Use the Browse… to choose a local folder.
Destination: It is the path of destination directory, a folder with the same name of source repository will be created within this directory.

Under the Options expander you will find:

Clone To Revision: You can limit the clone up to this revision. Even the tags created after this revision will not be imported.
Do not update the new working directory: If checked, after the clone the working directory will be empty. It is useful when you have to clone a repository with the purpose of central repository, or backup, where you have only, in the future, to push and pull.
Use pull protocol to copy metadata: When the source and destination are on the same filesystem, Mercurial tries to use hardlinks. Some filesystems, such as AFS implement hardlink incorrectly, but do not report errors. Use this option to avoid hardlinks.
Use uncompressed transfer: To use uncompressed transfer (fast over LAN).
Include patch queue: To also clone an MQ patch repository along with the main repository. It is possible to provide a patch queue name that differs from the default one.
Use proxy server: To use the proxy server configured in TortoiseHg… ‣ Global Settings ‣ Proxy. This is enabled only if a proxy is configured.
Do not verify host certificate: Skip checking server certificate for https:// url (ignoring web.cacerts config).
Remote command: Specify a Mercurial command to run on the remote side.
Hg command: This field displays the command that will be executed by the dialog.

From command line¶

The clone tool can be started from command line

thg clone

The syntax is

thg clone [SOURCE] [DEST]

where [SOURCE] and [DEST] are, the paths of source repository and destination folder.

Commit¶

The commit tool is second most commonly used application after the Workbench. Not only can the commit tool commit your changes, but it can also examine the state of your working directory and perform most routine maintenance tasks (add new files, detect renames, manage the ignore filter, etc).

Commit dialog

Features¶

Enumerating the toolbar buttons:

Branch dialog

Shows the current branch name of the working directory. Normally this is informational only, but pressing this button opens up a branch maintenance dialog. Do not use this feature unless you understand Mercurial’s named branches.

Recent Commit Messages

A drop-down list of the 10 most recent commit messages. The the drop-down list is filled the first time it is opened.

Commit

Commit selected diffs in checked files.

Undo

Undo (rollback) last immediate commit. Your commit message will be available in the message history, so you can easily repeat the commit if necessary.

The file list has four columns:

A checkbox that indicates whether the file is selected for an operation. The toolbar buttons only operate on checked files. “Partially” selected files have a special check state. This column header is checkable, it will toggle the file selection states.

The st column holds the status of the file, defined by Mercurial’s status command, one of ‘MARD?IC’. A status of ‘S’ indicates a dirty subrepository that needs to be committed.

The ms column holds the merge state of the file, defined by Mercurial’s resolve command, one of ‘ RU’. See the merge section below.

The canonical path of the file relative to the repository root

Note

If the commit tool was started with a file pattern or selection, a button will appear at the bottom of the file list that can clear the file pattern and give you an unfiltered view of the entire working directory.

The Status button has a menu with checkable options that toggle the display of the various classes of files {modified, added, removed, deleted, unknown, clean, ignored}.

Removed means a revisioned file has been marked as removed. Deleted means a revisioned file is missing but Mercurial has not been told to quit tracking that file. For instance, if you rename a revisioned file in Explorer, the original filename will show up as deleted and the new filename will show up as unknown. By right-clicking on the new filename you can bring up the rename guessing dialog which can discover the rename by comparing file contents and mark the old file as removed and the new file as added while recording the whole operation as a rename.

Unknown files are not tracked by Mercurial, but they also do not match any ignore filters you have configured. Unknown files are shown by default because they are usually files that need to be added to revision control. It is recommended that you keep your ignore filters up to date to ensure that is the case. The context menu of unknown files has an option open the ignore pattern tool.

Clean files are tracked files that have not been modified, while Ignored files are untracked files that match a configured ignore pattern. Neither of those file types are shown by default, unless a the user includes such a file in a selection (explorer) or provides the file name on the command line.

Change Selection¶

Change selection is the process of selecting which of the changes you have made to the working directory will be included in the next commit. The commit tool allows one to exclude modified (or added or removed) files from a commit, leaving them with their same state after the commit.

This somewhat violates Mercurial’s precept that each changeset describes the state of the repository at a single point in time. When you exclude files from the commit, the changeset you create may never have existed. But since file selection during commit is sometimes convenient, and is supported by Mercurial itself, our commit tool has supported this feature from its first release.

New in TortoiseHg 2.7, the commit tool now allows one to partially select modified files. This means you can now exclude a portion of the changes you have made to the file. This further violates Mercurial’s precept of committing the state of the working copy, but it is a very useful feature. The most commonly cited example is being able to check in a bug fix while excluding all your debug instrumentation so that you can continue debugging after the commit.

When the user has excluded one or more of the changes made to a file, TortoiseHg considers the file partially selected (and this change selection feature is sometimes referred to as partial commit). Partially selected files are displayed in the file list with a special partial check state.

The diff view pane has a context menu option for configuring the marking of excluded changes. Mark excluded changes toggles a strike-through indicator on excluded changes. This setting is primarily a personal preference, but future versions of TortoiseHg may extend the use of the strike-through indicator for partial exclusion of individual changes.

This new partial selection feature is similar to hgtk’s chunk selection, but is superior in several ways:

Change selection is integrated directly into the diff view. No mode switch is required.
The working copy files are not modified during partial commit. This avoids serious file permission problems on Windows.
Change selection is possible for copied or renamed files, with one exception. You cannot exclude all of the changes because this excludes the entire file from the commit.

TortoiseHg has had a shelve tool since version 2.0 which can move selected changes from the working directory to a patch (or between patches) but the partial commit feature is very different in that it never modifies the working copy files. All it is doing is excluding a portion of your changes from the version of the file which is committed to the repository. After the commit, all of your excluded changes will still remain in the working copy.

When the commit button is pressed, the commit tool checks if any of the checked files are partially excluded. If any such partial commits are required, the commit tool builds a temporary patch file which describes how to generate the contents of the partially excluded files and passes that patch file to TortoiseHg’s partial commit extension. This extension triggers Mercurial’s commit command with special hooks so that the partial commit file contents come from patched tempfiles instead of being read from the working copy. After the commit the temporary files and patch are deleted but the working copy files are completely untouched.

File Context Menus¶

When right clicking on files in the file list, you will get a context menu of commands that are applicable to the selected files.

For unknown ? files, the context menu will allow you to detect renames (if you think the unknown file is a copy or rename of a revisioned file) or to configure the repository’s ignore filter (if the unknown file should never be revisioned and you want Mercurial to ignore it).

Merging¶

The commit tool has a special mode when it is opened in a repository that is in a merged state (either a merge is in progress, or an update was performed that caused a conflict).

The merge state ms column is especially useful in this mode. Files that are marked with R are files where Mercurial and/or the user have successfully merged (resolved) changes from both parents. Files that are marked with U have unresolved changes. You can use the Restart Merge context menu option to restart the merge for those files, or you can use the edit context menu option to resolve the conflict by hand. The Restart Merge menu option allows you to select the merge tool to use to perform the merge, or even to pick one version or the other unconditionally (internal:local, internal:other). After the conflicts have been manually resolved, you must use the mark resolved context menu option to change the file’s merge state to R.

Mercurial will not allow you to commit a merge if any files have unresolved U merge states.

For your reference, local is the revision you had checked out when you started the merge and other is the revision you merged with.

To undo a failed merge attempt, you must tell Mercurial to remove the second parent from your working directory. This usually means performing a clean update of the first parent. The merge tool has an Undo button which does exactly that.

Once you have your working directory back at one parent revision, you may restart the merge process.

Commit Message Pane¶

The commit message pane has these special context menu options:

Paste Filenames:

Paste checked filenames into the commit message at the cursor.

Apply Format:

Apply configured message wrap policy to current message.

Configure Format:

Opens the settings dialog to the Commit tab.

If your project has guidelines for the format of commit messages, you can configure them in the settings tool. The commit tool will enforce your policy at commit time, and you can ask the tool to apply the format to the current message. The Commit tab of the settings tool has these two configurables for commit message policy:

Summary Line Length:

Maximum length of the commit message summary line. If set, TortoiseHg will draw a line at the specified width.

Subrepositories¶

A subrepository is a feature introduced in Mercurial 1.3. It allows one Mercurial repository to store references to external Mercurial (or potentially other VCS) repositories, and to include the state of those external repositories in the main repository’s history.

TortoiseHg 1.0 introduced rudimentary support for subrepositories, and only in the commit / status tool. When Mercurial considers a subrepo dirty, it will appear in the commit tool as a special entry in the file list with a status of S. If a subrepo is included in the file list of a commit, the subrepo is committed along with the other changes, updating the .hgsubstate file in the main repository root.

Configurables¶

Commit ‣ Username: Sets username associated with your commits (see A Quick Start Guide to TortoiseHg)
Commit ‣ Summary Line Length: Configures a ‘policy’ limit for summary lines
Commit ‣ Close After Commit:: When set to True, the commit tool will close after a successful commit.

And three other features for advanced users.

Commit ‣ Push After Commit:: If configured, the commit tool will try to push to the configured URL or alias after each commit.
Commit ‣ Auto Commit List:: Comma separated list of files that are automatically included in every commit. Intended for use only as a repository setting.
TortoiseHg ‣ Max Diff Size: Configures the diff size limit

From command line¶

The commit tool can be started from command line:

thg commit [OPTIONS] [FILE]...

aliases: ci

commit tool

options:

 -u --user  record user as committer
 -d --date  record datecode as commit date

use "thg -v help commit" to show global options

For a quick help on the format of date type:

hg help dates

Shelve¶

The shelve tool can move changes between the working directory and shelf patches. If the MQ extension has been enabled, it can also move changes into and out of unapplied patches.

The shelve tool can be launched by the Workbench Repository –> Shelve menu option, by a toolbar button on working file viewers, or by thg shelve.

Note

We highly recommend setting the patch eol configuration to auto if you use the shelve tool with DOS eoln text files.

Shelve dialog

Features¶

The shelve tool has three toolbars. A right and left toolbar for the two side by side panels, and a central toolbar for refresh and creating a new shelf patch. The right and left toolbars are mirrors of each other, offering the same functionality in alternate directions.

The left toolbar has these actions:

Delete selected chunks

Remove, or revert, all selected (toggled) chunks in the currently selected file.

Move all files right

Move all changes in all files to the patch selected in the right pane.

Move selected file right

Move all changes in the currently selected file to the patch selected in the right pane.

Edit selected file

If the working directory is being browsed, this button edits the currently selected file. Else it edits the currently viewed patch file.

Move selected chunks right

Move all selected (toggled) chunks to the patch selected in the right pane.

The central toolbar has two actions:

Refresh

Refreshes the patch drop down lists and the working copy view

New Shelf

Creates a new shelf file. You must enter a name, though a reasonable default is provided.

The right toolbar will move changes from the patch selected on the left side to the patch selected on the right side, or the working copy if it has been selected on the right.

Patch Panes¶

The right and the left patch panes are identical save for the working copy changes are only available on the left. Selectable chunks are only displayed if the file is text and is in a modified state. Added or removed files can be shelved but parts of the file cannot be individually selected.

The Clear button will empty the currently selected patch or revert the entire working copy. The Delete button will delete the currently selected shelf patch.

Note

The Delete button is not sensitive when an MQ patch is selected. MQ patches must be deleted via qdelete using the Workbench context menu or the Patch Queue widget.

When right clicking on a file in the file list, you will get a context menu of commands.

Visual Diff

Open the selected file in your default visual diff tool. Only enabled for working copy files.

Edit Local

Open the working copy version of the selected file.

Revert to Revision

Revert all changes to the selected file. Only enabled for working copy files.

Trashcan¶

The shelve tool is very conservative with your source and patch files. Before it modifies any file it makes a backup under .hg/Trashcan. This trashcan can be emptied by running the purge dialog from the Workbench Repository –> Purge menu option.

From command line¶

The shelve tool can be started from command line:

thg shelve

aliases: unshelve

shelve tool

use "thg -v help shelve" to show global options

Synchronize¶

Synchronize dialog

The synchronize tool is used to transmit changesets between repositories or to email recipients.

Incoming

show changesets that would be pulled from target repository, the changes in the target repository that are not in local repository

Pull

pull incoming changesets from target repository

Outgoing

show changesets that would be pushed to target repository, the changes in the local repository that are not in target repository

Push

push outgoing changesets to target repository, make the local tip the new tip in the target repository

Email

send outgoing changesets (to target repository) as email

Stop

stop current operation

The Post Pull dialog contains radio buttons for selecting the operation which is performed after a pull. If you open the configuration tool, you can select a default behavior for your user account and override that selection on a per-repository basis.

None

No operations are performed after a pull. You will be allowed to view the pulled changesets in the log viewer, and you will have the option to update to the new tip if applicable.

Update

Automatically update to the current branch tip if, and only if, new revisions were pulled into the local repository. This could trigger a merge if the pulled changes conflict with local uncommitted changes.

Fetch

Equivalent to hg fetch. See the fetch extension documentation for its behavior. This feature is only available if the fetch extension has been enabled by the user.

Rebase

Equivalent to pull –rebase. See the rebase extension documentation for its behavior. This feature is only available if the rebase extension has been enabled by the user.

Automatically resolve merge conflicts where possible

If update or rebase are selected, a pull operation may result in a merge. If checked, Mercurial will try to resolve trivial merge conflicts without user interaction. If not checked, all merges will be interactive.

The Options dialog provides checkboxes for selecting infrequently used command options.

Allow push of a new branch

allow a new named branch to be pushed

Force pull or push

override warnings about multiple heads or unrelated repositories

Recurse into subdirectories

incoming or outgoing commands can recurse into subdirectories and provide a full report

Temporarily disable configured proxy

only sensitive when a web proxy is configured for the given repository. While checked it will disable that proxy.

Remote Command

provides a –remotecmd argument

When the sync tool is opened within the Workbench, the toolbar has a Target checkbox. While checked, the target dropdown box is sensitive and the selected target revision, bookmark, or branch will be added to every synchronization command. When the sync tool is opened outside of the Workbench, the target checkbox and dropdown box is hidden. Clicking on a revision in the graph will update the values in the dropdown box. Holding Alt while clicking on a revision will select the revision without switching away from the sync tool tab.

Below the toolbar is the currently selected URL. All synchronization commands will use this URL. The general effect of the toolbar is that it can be read as a Mercurial command line. The tool buttons select the command, the Post Pull and Options dialog specify options, the target dropdown box can specify revisions, and finally the URL completes the command.

Adding an URL¶

By far the easiest way to add a new URL to your respository is to drag and drop the URL from another application, then press the save button and provide the URL an alias.

The two list panes display URLs that are stored in the current repository’s configuration file (Stored Paths) and URLs that are stored in other related repositories that are listed in the Workbench repository registry (Related Paths). When the sync tool is opened outside of the Workbench, the Related Paths list will be empty.

Note

Being related means two repositories share at least a common root changeset. Cloned are obviously related. Push and pull operations require that repositories to be related, or that you use –force to override the relationship check.

The URL lists have a context menu that allows you to browse, open a terminal, or delete an URL from your local configuration file. The platform standard delete key sequence will also remove an URL.

Security¶

Mercurial (and TortoiseHg) support two secure protocols for exchanging data with remove servers. HTTPS (SSL) and SSH.

HTTPS¶

There are two asymmetrical parts to a secure HTTPS connection. The first part of the secure connection is authenticating the identification of the server. The second is authenticating yourself (the client) to the server, either via a username and passphrase or a certificate key.

Host Authentication¶

Prior to version 1.7, Mercurial ignored this half of HTTPS connection security. In version 1.7 it began warning that the server’s certificate was not being verified.

Mercurial version 1.7.5 introduced the ability to validate an HTTPS server’s certificate against a stored fingerprint. TortoiseHg 2.0’s synchronize tool has an HTTPS security dialog that allows you to select between using a host fingerprint or using the CA certificates.

In theory, a host fingerprint is more secure than the CA certificates if you do not necessarily trust all of the signing authorities listed in the default store. However you must be sure that the fingerprint you store is the correct fingerprint for the server to which you believe you are communicating.

TortoiseHg 2.0 also allows you to select an insecure connection for a given host. This disables validation of the host’s certificate but still uses an encrypted data stream (which was essentially the behavior of Mercurial pre-1.7 except for the warning messages).

User Authentication¶

There are several mechanisms available for authenticating yourself to an HTTPS server. The simplest is to allow Mercurial to prompt you for the username and passphrase. However this quickly grows old as the two prompts are always made separately and each push operation can require multiple connections to be established.

The next option is to encode the username in the URL so that Mercurial only prompts for a passphrase. This cuts the number of prompts in half, but is still annoying. If you do not wish to be prompted for the passphrase, it must be stored somewhere. Your choices, in increasing security, are:

encode the clear-text passphrase in each HTTPS URL in your repository configuration files
store the clear-text passphrase in your user configuration file
use the mercurial_keyring extension to store the passphrase cryptographically

Until recently, TortoiseHg only supported the first option in the graphical interface even though the second and third options were supported internally. TortoiseHg 2.0, we only support the latter two options in the graphical interface, and we do not allow the user configure the first option anymore. By default we strip the username and password off of URLs when they are saved.

To migrate from the first option to the later options, select an HTTPS URL in the sync tool, open the security dialog and enter a username and passphrase for the host if none are configured, and save. Next save the URL itself and allow the save dialog to strip the user authentication data from the URL.

Note

If the mercurial_keyring extension is enabled, the security dialog will not allow you to enter a passphrase since you do not want to store the passphrase in clear text in your configuration file if you are going to later store it cryptographically.

Options 2 and 3 use the [auth] section of your user configuration file to configure a single username and passphrase (or certificate key files) to authenticate to a given HTTPS hostname. The [auth] section supports many more configurations than this, see the man page for details.

Once the mercurial_keyring extension has been enabled (and all applications are restarted), you can remove the HTTPS passphrases from all of your configuration files. Mercurial will prompt for the passphrase once, then store it cryptographically using the best back-end it can find for your platform.

The mercurial_keyring extension requires the [auth] section to be configured for the host to which you are connecting, to provide the username. If your URL has an encoded username or passphrase, the [auth] section is ignored.

SSH¶

SSH is a symmetrical peer-to-peer secure tunnel. SSH clients and servers have their own key management systems, so Mercurial does not get involved with password prompts when SSH is used. This is problematic on Windows and thus TortoiseHg bundles the TortoisePlink SSH client with its Windows installers. TortoisePlink is a port of the Plink SSH client that uses dialog prompts for host-key authorizations and passphrase prompts. TortoisePlink (developed by the TortoiseSVN project) can use the other SSH tools that are part of the Plink toolchain, including the Pageant key agent.

It is a known issue that TortoisePlink does not use compression in many scenarios, and thus is up to four times slower than openssh and other clients. TortoiseHg recommends the use of HTTPS for Windows clients.

See the Frequently Asked Questions for help if you have trouble connecting to ssh servers.

Email¶

Email dialog

The email dialog can be launched from two TortoiseHg tools.

The Workbench, in which case the user intends to email a selection of revisions.
The synchronize tool, in which case the user intends to email all outgoing changes to the current target repository.

The Send button is obvious, and the Configure dialog predictably opens the TortoiseHg Settings dialog to the email tab where you can configure your SMTP settings and set default To: and From: addresses.

In-Reply-To: is used to make your patches properly threaded in mailing lists.

Please consult the Mercurial documentation for the differences between plain patches, Hg patches, Git patches, and bundles.

From command line¶

The synchronize tool can be started from command line

thg sync

aliases: synchronize

Synchronize with other repositories

use "thg -v help sync" to show global options

The syntax is simple, no options or parameters are needed, except the global options.

Serve¶

Mercurial comes with an in-built, light-weight web server capable of serving a single repository for single connection. Serve does not provide user authentication, but does provide a convenient, ad-hoc method of synchronizing a repository over a local network. For more complete information on publishing repositories, see the Mercurial wiki article on Publishing Repositories.

From TortoiseHg¶

The serve tool is a wrapper for Mercurial’s built-in web server. Once launched, a computer can connect to the http port and browse your repositories, perform clone, pull, or even push operations if enabled. The web server can be launched from either the Workbench (Repository Menu) or the Context Menu.

Toolbar buttons:

Start

start the web server

Stop

stop the web server

Configure

Configure repository web style, description, and access policies

When the settings dialog is launched via the Configure button, it is run in the context of the current repository. Please visit the Mercurial wiki for detailed descriptions of the various web configurations.

In TortoiseHg 2.0, the serve tool natively supports collections of local repositories. Just drag them onto the web serve dialog while it is not running, or add them by hand using the editing buttons. The repository collections can be saved and reloaded.

From command line¶

The server tool can be started from command line

thg serve [OPTION]...

start stand-alone webserver

options:

        --webdir-conf  name of the webdir config file

use "thg -v help serve" to show global options

Detect Renames¶

Rename Guessing Dialog

This dialog is used to find renames, moves, and/or copies that were done without Mercurial’s knowledge. The dialog can be launched from the shell context menu, or from the status or commit tools via the context menu of an unknown file.

Follow these steps:

select one or more of the Unrevisioned Files
slide the Min Similarity bar to the percentage match you desire
uncheck Only consider deleted files to search for copies
press Find Rename
preview Candidate Matches and accept good matches
repeat until all unrevisioned files are matched

Candidate Matches¶

When you select a match in this list, the differences between the two files are shown in the bottom pane. Pressing Accept Match will record the rename or copy event with Mercurial.

From command line¶

The guess tool can be started from command line:

thg guess

guess previous renames or copies

use "thg -v help guess" to show global options

Ignore Filter¶

The ignore dialog is used to maintain your Mercurial repository’s ignore filter, which can be found in an .hgignore file in the repository root. The dialog can be launched from the shell context menu, or from the status or commit tools via the context menu of an unknown file. The Glob combo allows to switch between glob or regexp patterns.

Ignore Filter Dialog

From command line¶

The ignore tool can be started from command line:

thg hgignore [FILE]

aliases: ignore, filter

ignore filter editor

use "thg -v help hgignore" to show global options

Archiving¶

You can choose from quite a lot of formats to make an archive of a repository. There are the usual compressed formats, of course, but it’s also possible to make a folder of the uncompressed files in a place other than the Working Directory (like a clone, but without the .hg folder). Such archives, for example, can be useful for doing builds (similar to ‘svn export’). Archives may also be useful for sending changes to external people without access to the reposity, where only the effected files of a given revision or set of revisions need be included in the archive.

From TortoiseHg¶

From the changelog context menu in the Workbench select Export ‣ Archive… for the choosen changeset.

Repository Archive Dialog

Revision: To select the revision you wish to archive or export.
Only files modified/created in this revision: To limit the number of files in the archive.
Destination path: The filename or directory where the archive will be created. The archive is filled with the name of the current repository, suffixed with the revision number of the selected revision, and has the appropriate extension of the selected archive type.
Archive types: Here you can choose the type of archive to create, ranging from a plain folder with files to a variety of standard archive type.
Hg command: This field displays the command that will be executed by the dialog.
Always show output: To have an logging output pane with the results of the command while it runs.

Archiving a repository means create an archive file or subdirectory with the contents of the selected revision.

From command line¶

The archive tool can be started from command line

thg archive

The syntax is

thg archive -r [REV] -t [TYPE] [DEST]

where [REV] is the revision to archive, [TYPE] is the type of archive to create, and [DEST] is the name of the file or folder to create.

See hg.1.html#archive for details, or type hg help archive at the command line or in the Output Log of the Workbench.

Settings¶

Settings dialog

The Settings dialog is used to configure both TortoiseHg and the underlying Mercurial DVCS. Since TortoiseHg uses Mercurial’s underlying configuration system to store and retrieve its settings, these are essentially the same thing.

Mercurial on Windows has a three-tier configuration system.

A site-wide configuration file in C:\Program Files\TortoiseHg\Mercurial.ini This file is read first and thus has the lowest priority.
A per-user configuration file in C:\Documents and Settings\username\Mercurial.ini This file is read second and thus can override settings in the site-wide configuration file.
A per-repository configuration file in repo-root\.hg\hgrc This file is read last and can override site-wide and user global settings.

The site-wide file can be overwritten on upgrades so it is recommended that you do not make changes to this file. Instead, you should make changes to your user Mercurial.ini and/or the repository hgrc file. The TortoiseHg Settings dialog enforces this suggestion by only operating in two modes:

Global: edits your user Mercurial.ini file
Repository: edits a repository .hg/hgrc file

You may toggle between the two modes using the combo box at the top of the dialog, or directly edit the file in your configured visual editor.

Most TortoiseHg users will want to store all configurables in their global user settings, and only use the repository hgrc to store paths (remote repository aliases) and web settings, though it is possible to override many configurables per-repository (a common example is to configure a username for use in a specific repository). Also note that the user and repository configuration files may not exist until you run the Settings dialog for the first time.

Tabs¶

The Settings tool is a tabbed application.

Each tab corresponds roughly to a section of your Mercurial.ini file, though there is a certain amount of overlap. Some sections were split across multiple tabs for clarity.

Every tab but Sync has the same format, a list of configurable options with a drop-down combo box with possible values and a history of options you have used for that setting. The configurable name (label) has a tooltip which describes in more detail what you are configuring and its default value. The description of the currently focused configurable is also shown in a text box at the bottom of the dialog.

Please consult the Mercurial wiki for more detailed information about these configurables (except for the first three tabs: TortoiseHg, Commit, Changelog, which are specific to TortoiseHg).

TortoiseHg¶

UI Language:

Specify your preferred user interface language (restart needed)

3-way Merge Tool:

Graphical merge program for resolving merge conflicts. If left unspecified, Mercurial will use the first applicable tool it finds on your system or use its internal merge tool that leaves conflict markers in place. Chose internal:merge to force conflict markers, internal:prompt to always select local or other, or internal:dump to leave files in the working directory for manual merging.

Visual Diff Tool:

Specify visual diff tool as described in the [merge-tools] section of your Mercurial configuration files. If left unspecified, TortoiseHg will use the selected merge tool. Failing that it uses the first applicable tool it finds.

Visual Editor:

Specify visual editor, as described in the [editor-tools] section of your Mercurial configuration files. If left unspecified, TortoiseHg will use the first applicable tool it finds.

CLI Editor:

The editor used by Mercurial command line commands to collect multiline input from the user. Most notably, commit messages.

Shell:

Specify the command to launch your preferred terminal shell application. If the value includes the string %(reponame)s, the name of the repository will be substituted in place of %(reponame)s. Similarly, %(root)s will be the full path to the repository. (restart needed)

Default, Windows:: cmd.exe /K title %(reponame)s
Default, OS X:: not set
Default, other:: xterm -T "%(reponame)s"

Immediate Operations:

Space separated list of shell operations you would like to be performed immediately, without user interaction. Commands are “add remove revert forget”. Default: None (leave blank)

Tab Width:

Specify the number of spaces that tabs expand to in various TortoiseHg windows. Default: 8

Force Repo Tab:

Always show repo tabs, even for a single repo. Default: False

Monitor Repo Changes:

Specify the target filesystem where TortoiseHg monitors changes. Default: localonly

Max Diff Size:

The maximum size file (in KB) that TortoiseHg will show changes for in the changelog, status, and commit windows. A value of zero implies no limit. Default: 1024 (1MB).

Fork GUI:

When running thg from the command line, fork a background process to run graphical dialogs. Default: True.

Full Path Title:

Show a full directory path of the repository in the dialog title instead of just the root directory name. Default: False

Auto-resolve merges:

Indicates whether TortoiseHg should attempt to automatically resolve changes from both sides to the same file, and only report merge conflicts when this is not possible. When False, all files with changes on both sides of the merge will report as conflicting, even if the edits are to different parts of the file. In either case, when conflicts occur, the user will be invited to review and resolve changes manually. Default: True.

New Repo Skeleton:

If specified, files in the directory, e.g. .hgignore, are copied to the newly-created repository.

Workbench¶

Single Workbench Window:

Select whether you want to have a single workbench window. If you disable this setting you will get a new workbench window everytime that you use the “Hg Workbench” command on the explorer context menu. Default: True

Default widget:

Select the initial widget that will be shown when opening a repository. Default: revdetails

Initial revision:

Select the initial revision that will be selected when opening a repository. You can select the “current” (i.e. the working directory parent), the current “tip” or the working directory (“workingdir”). Default: current

Open new tabs next to the current tab:

Should new tabs be open next to the current tab? If False new tabs will be open after the last tab. Default: True

Author Coloring:

Color changesets by author name. Default: False

Full Authorname:

Show full authorname in Logview. If not enabled, only a short part, usually name without email is shown. Default: False

Task Tabs:

Show tabs along the side of the bottom half of each repo widget allowing one to switch task tabs without using the toolbar. Default: off

Task Toolbar Order:

Specify which task buttons you want to show on the task toolbar and in which order. Type a list of the task button names. Add separators by putting “|” between task button names. Valid names are: log commit sync grep. Default: log commit grep | sync

Long Summary:

If true, concatenate multiple lines of changeset summary and truncate them at 80 characters as necessary. Default: False

Log Batch Size:

The number of revisions to read and display in the changelog viewer in a single batch. Default: 500

Dead Branches:

Comma separated list of branch names that should be ignored when building a list of branch names for a repository. Default: None (leave blank)

Branch Colors:

Space separated list of branch names and colors of the form branch:#XXXXXX. Spaces and colons in the branch name must be escaped using a backslash (\). Likewise some other characters can be escaped in this way, e.g. \u0040 will be decoded to the @ haracter, and \n to a linefeed. Default: None (leave blank)

Hide Tags:

Space separated list of tags that will not be shown. Useful example: Specify “qbase qparent qtip” to hide the standard tags inserted by the Mercurial Queues Extension. Default: None (leave blank)

Activate Bookmarks:

Select when TortoiseHg will show a prompt to activate a bookmark when updating to a revision that has one or more bookmarks.

auto :

Try to automatically activate bookmarks. When updating to a revision that has a single bookmark it will be activated automatically. Show a prompt if there is more than one bookmark on the revision that is being updated to.

prompt :

The default. Show a prompt when updating to a revision that has one: or more bookmarks.

never :

Never show any prompt to activate any bookmarks.

Default: prompt

Show Family Line:

Show indirect revision dependency on the revision graph when filtered by revset. Default: True

Note

Calculating family line may be slow in some cases. This option is expected to be removed if the performance issue is solved.

Commit¶

Username:

Name associated with commits. The common format is: Full Name <email@example.com>

Ask Username:

If no username has been specified, the user will be prompted to enter a username. Default: False

Summary Line Length:

Suggested length of commit message lines. A red vertical line will mark this length. CTRL-E will reflow the current paragraph to the specified line length. Default: 80

Close After Commit:

Close the commit tool after every successful commit. Default: False

Push After Commit:

Attempt to push to default push target after every successful commit. Default: No push

Auto Commit List:

Comma separated list of files that are automatically included in every commit. Intended for use only as a repository setting. Default: None (leave blank)

Auto Exclude List:

Comma separated list of files that are automatically unchecked when the status, and commit dialogs are opened. Default: None (leave blank)

English Messages:

Generate English commit messages even if LANGUAGE or LANG environment variables are set to a non-English language. This setting is used by the Merge, Tag and Backout dialogs. Default: False

New Commit Phase:

The phase of new commits. Default: draft

Secret MQ Patches:

Make MQ patches secret (instead of draft). Default: False

Check Subrepo Phase:

Check the phase of the current revision of each subrepository. For settings other than “ignore”, the phase of the current revision of each subrepository is checked before committing the parent repository. Default: follow

Monitor working directory changes:

Select when the working directory status list will be refreshed:

auto : default: let TortoiseHg decide when to refresh the working directory status list. TortoiseHg will refresh the status list whenever it performs an action that may potentially modify the working directory. This may miss any changes that happen outside of TortoiseHg’s control;
always :: in addition to the automatic updates above, also refresh the status list whenever the user clicks on the “working dir revision” or on the “Commit icon” on the workbench task bar;
alwayslocal :: same as always but restricts forced refreshes to local repos.

Default: auto

Confirm adding unknown files:

Determines if TortoiseHg should show a confirmation dialog before adding new files in a commit. If True, a confirmation dialog will be shown. If False, selected new files will be included in the commit with no confirmation dialog. Default: True

Confirm deleting files:

Determines if TortoiseHg should show a confirmation dialog before removing files in a commit. If True, a confirmation dialog will be shown. If False, selected deleted files will be included in the commit with no confirmation dialog. Default: True

Sync¶

After Pull Operation:

Operation which is performed directly after a successful pull. update equates to pull --update, fetch equates to the fetch extension, rebase equates to pull --rebase, updateorrebase equates to

pull
-u --rebase

. Default: none

Default Push:

Select the revisions that will be pushed by default, whenever you click the Push button.

all :: The default. Push all changes in all branches.
branch :: Push all changes in the current branch.
revision :: Push the changes in the current branch up to the current revision.

Default: all

Confirm Push:

Determines if TortoiseHg should show a confirmation dialog before pushing changesets. If False, push will be performed without any confirmation dialog. Default: True

Target Combo:

Select if TortoiseHg will show a target combo in the sync toolbar.

auto :: The default. Show the combo if more than one target configured.
always:: Always show the combo.

Default: auto

SSH Command:

Command to use for SSH connections.

Default: ssh or TortoisePlink.exe -ssh -2 (Windows)

Server¶

Repository Details:

Name:: Repository name to use in the web interface, and by TortoiseHg as a shorthand name. Default is the working directory.
Encoding:: Character encoding of files in the repository, used by the web interface and TortoiseHg.
‘Publishing’ repository:: Controls draft phase behavior when working as a server. When true, pushed changesets are set to public in both client and server and pulled or cloned changesets are set to public in the client. Default: True

Web Server:

Description:: Textual description of the repository’s purpose or contents.
Contact:: Name or email address of the person in charge of the repository.
Style:: Which template map style to use.
Archive Formats:: Comma separated list of archive formats allowed for downloading.
Port:: Port to listen on.
Push Requires SSL:: Whether to require that inbound pushes be transported over SSL to prevent password sniffing.
Stripes:: How many lines a “zebra stripe” should span in multiline output. Default is 1; set to 0 to disable.
Max Files:: Maximum number of files to list per changeset.
Max Changes:: Maximum number of changes to list on the changelog.
Allow Push:: Whether to allow pushing to the repository. If empty or not set, push is not allowed. If the special value “*”, any remote user can push, including unauthenticated users. Otherwise, the remote user must have been authenticated, and the authenticated user name must be present in this list (separated by whitespace or “,”). The contents of the allow_push list are examined after the deny_push list.
Deny Push:: Whether to deny pushing to the repository. If empty or not set, push is not denied. If the special value “*”, all remote users are denied push. Otherwise, unauthenticated users are all denied, and any authenticated user name present in this list (separated by whitespace or “,”) is also denied. The contents of the deny_push list are examined before the allow_push list.

Proxy¶

Host:: Host name and (optional) port of proxy server, for example myproxy:8000.
Bypass List:: Optional. Comma-separated list of host names that should bypass the proxy.
User:: Optional. User name to authenticate with at the proxy server.
Password:: Optional. Password to authenticate with at the proxy server.

Email¶

From:: Email address to use in the “From” header and for the SMTP envelope.
To:: Comma-separated list of recipient email addresses.
Cc:: Comma-separated list of carbon copy recipient email addresses.
Bcc:: Comma-separated list of blind carbon copy recipient email addresses.
method:: Optional. Method to use to send email messages. If value is “smtp” (default), use SMTP (configured below). Otherwise, use as name of program to run that acts like sendmail (takes -f option for sender, list of recipients on command line, message on stdin). Normally, setting this to sendmail or /usr/sbin/sendmail is enough to use sendmail to send messages.
SMTP Host:: Host name of mail server.
SMTP Port:: Port to connect to on mail server. Default: 25.
SMTP TLS:: Method to enable TLS when connecting to mail server. Default: none
SMTP Username:: Username to authenticate to mail server with.
SMTP Password:: Password to authenticate to mail server with.
Local Hostname:: Hostname the sender can use to identify itself to the mail server.

Diff and Annotate¶

Patch EOL:: Normalize file line endings during and after patch to lf or crlf. Strict does no normalization. Auto does per-file detection, and is the recommended setting. Default: strict
Git Format:: Use git extended diff header format. Default: False.
MQ Git Format:: When set to auto, mq will automatically use git patches when required to avoid losing changes to file modes, copy records or binary files. If set to keep, mq will obey the [diff] section configuration while preserving existing git patches upon qrefresh. If set to yes or no, mq will override the [diff] section and always generate git or regular patches, possibly losing data in the second case. Default: auto
No Dates:: Do not include modification dates in diff headers. Default: False.
Show Function:: Show which function each change is in. Default: False.
Ignore White Space:: Ignore white space when comparing lines. Default: False.
Ignore WS Amount:: Ignore changes in the amount of white space. Default: False.
Ignore Blank Lines:: Ignore changes whose lines are all blank. Default: False.

Annotate:

Ignore White Space:: Ignore white space when comparing lines in the annotate view. Default: False
Ignore WS Amount:: Ignore changes in the amount of white space in the annotate view. Default: False
Ignore Blank Lines:: Ignore changes whose lines are all blank in the annotate view. Default: False

Font¶

Message Font:: Font used to display commit messages. Default: monospace 10
Diff Font:: Font used to display text differences. Default: monospace 10
List Font:: Font used to display file lists. Default: sans 9
ChangeLog Font:: Font used to display changelog data. Default: monospace 10
Output Font:: Font used to display output messages. Default: sans 8

Issue Tracking¶

Issue Regex:

Defines the regex to match when picking up issue numbers.

Issue Link:

Defines the command to run when an issue number is recognized. You may include groups in issue.regex, and corresponding {n} tokens in issue.link (where n is a non-negative integer). {0} refers to the entire string matched by issue.regex, while {1} refers to the first group and so on. If no {n} tokens are found in issue.link, the entire matched string is appended instead.

Inline Tags:

Show tags at start of commit message.

Mandatory Issue Reference:

When committing, require that a reference to an issue be specified. If enabled, the regex configured in ‘Issue Regex’ must find a match in the commit message.

Issue Tracker Plugin:

Configures a COM IBugTraqProvider or IBugTraqProvider2 issue tracking plugin.

Configure Issue Tracker:

Configure the selected COM Bug Tracker plugin.

Issue Tracker Trigger:

Determines when the issue tracker state will be updated by TortoiseHg. Valid settings values are:

never :: Do not update the Issue Tracker state automatically.
commit :: Update the Issue Tracker state after a successful commit.

Default: never

Changeset Link:

A “template string” that, when set, turns the revision number and short hashes that are shown on the revision panels into links. The “template string” uses a “mercurial template”-like syntax that currently accepts two template expressions:

{node|short} :: replaced by the 12 digit revision id (note that {node} on its own is currently unsupported).
{rev} :: replaced by the revision number.

For example, in order to link to bitbucket commit pages you can set this to: https://bitbucket.org/tortoisehg/thg/commits/{node|short}

Review Board¶

Server:: Path to review board example http://demo.reviewboard.org
User:: User name to authenticate with review board
Password:: Password to authenticate with review board
Server Repository ID:: The default repository id for this repo on the review board server
Target Groups:: A comma separated list of target groups
Target People:: A comma separated list of target people

Largefiles¶

Patterns:: Files with names meeting the specified patterns will be automatically added as largefiles
Minimum Size:: Files of at least the specified size (in megabytes) will be added as largefiles
User Cache:: Path to the directory where a user’s cache of largefiles will be stored

Projrc¶

Require confirmation:

When to ask the user to confirm the update of the local “projrc” configuration file when the remote projrc file changes. Possible values are:

always : default: Always show a confirmation prompt before updating the local .hg/projrc file.
first :: Show a confirmation dialog when the repository is cloned or when a remote projrc file is found for the first time.
never :: Update the local .hg/projrc file automatically, without requiring any user confirmation.

Servers:

List of Servers from which “projrc” configuration files must be pulled. Set it to “*” to pull from all servers. Set it to “default” to pull from the default sync path. Default is pull from NO servers.

Include:

List of settings that will be pulled from the project configuration file. Default is include NO settings.

Exclude:

List of settings that will NOT be pulled from the project configuration file. Default is exclude none of the included settings.

Update on incoming:

Let the user update the projrc on incoming:

never : default: Show whether the remote projrc file has changed, but do not update (nor ask to update) the local projrc file.
prompt :: Look for changes to the projrc file. If there are changes always show a confirmation prompt, asking the user if it wants to update its local projrc file.
auto :: Look for changes to the projrc file. Use the value of the “projrc.confirm” configuration key to determine whether to show a confirmation dialog or not before updating the local projrc file.

Default: never

GnuPG¶

Command:: Specify the path to GPG. Default: gpg
Key ID:: GPG key ID associated with user. Default: None (leave blank)

From command line¶

The setting dialog can be started from command line

thg repoconfig

for the repository settings (.hg/hgrc file) or

thg userconfig

for the user configuration (Mercurial.ini file).

The syntax is simple, no options or parameters are needed, except the global options.

Patches¶

Defining a patch¶

These links are recommended reading for understanding the history and nature of patches and how they can be used with Mercurial.

Pitfalls¶

The standard patch format cannot describe binary files, renames, copies, or permission changes. If your patch needs to record any of those things, you will need to enable git patches via:

[diff]
git=True

Mercurial 1.5 improves its behavior in this regard. It will warn you when git diffs are required, or sometimes upgrade to the git format automatically. See also the diff section of the hgrc documentation.

Mercurial’s patch routines do not deal well with mixed EOLN between source files and patches. The patch.eol setting was introduced in 1.3 to improve this situation:

[patch]
eol = auto #strict, lf, or crlf

Note

When eol is set to auto, the patching engine will preserve the line endings of the patched file regardless of the line endings in the patch itself. You almost always want eol to be configured to auto. The only downside is that you cannot make a patch that changes the line endings of a source file.

See also the patch section of the hgrc documentation.

Applying a patch is not a foolproof operation. If the source file has diverged from the file that was used to create the patch, there may be conflicts during the patch application. These are written to a file with an .rej extension. TortoiseHg 2.0 includes a thg rejects command that can aid in the merging of the rejected chunks into the source file.

Export Patches¶

Changeset¶

To export a changeset as a patch file, use the changeset context menu of the Workbench to select Export ‣ Export Patch. It writes the changeset to a file in the repository root folder.

Changeset Ranges¶

Select the start and end of a range of changesets in the Workbench and open the special revision range context menu. From this menu you can generate patches, generate a bundle, send emails, or visually diff the accumulated changes.

This is a very powerful feature and there is no restriction on the base and target changesets you can select.

Email¶

Email dialog of Workbench

To send a changeset as an email, use the changeset context menu of the Workbench. Export ‣ Email Patch. This opens the e-mail dialog for this single changeset.

To send a changeset range, use the changeset range selection feature of the Workbench and select Email selected… or Email DAG range….

Lastly, you can use the Email button on the sync tab of the Workbench to email all outgoing changes to the selected remote repository.

Note

You must configure SMTP to send patches via email

Import Patches¶

Import dialog of the WorkBench

The import dialog can be opened from the Repository menu of the Workbench, or via thg import. The dialog supports file and directory drag and drop.

You have the choice of importing directly into the repository, the working folder, a shelf file, or your patch queue.

Note

Importing a patch requires a clean working directory state. You must commit, revert, or shelve changes before importing a patch.

Note

If a patch does not import itself cleanly into the repository, the recommended recourse is to import the patch into your patch queue (qimport) and then qpush the patch. This uses TortoiseHg patch rejection dialog and preserves the meta-data in the patch header. Do not forget to qrefresh after resolving the rejected chunks.

Warning

If the patch you are importing does not have a commit message, Mercurial will try to launch your editor, just as if you had tried to import the patch from the command line. Your ui.editor needs to be a GUI app to make this work correctly.

Patch Queues¶

A patch queue in the repository graph

When MQ is enabled, several Workbench features are exposed. Context menu options are exposed in the changeset menus, your patch queue is graphed together with your repository’s history, and a Patch Queue is activated.

Double clicking on an unapplied patch, an applied patch other than the current qtip, or the qparent triggers a qgoto command; making the double clicked revision the current patch. Double clicking on any other revision will trigger a visual diff of that revision.

Note

The Workbench must be restarted after enabling or disabling the MQ extension in a repository. This is true of most extensions.

Note

It is recommended to learn the MQ extension before using the MQ features of the Workbench.

Changed in version 2.10: The Patch Queue task tab has been superseded by the Commit task tab and the Patch Queue dock.

Patch Rejects¶

As explained previously, patches are not guaranteed to apply cleanly to their intended source files. Prior to TortoiseHg 2.0, the only recourse available when patch chunks were rejected was to open the source file and the rejects file in an editor and manually fixup the rejected chunks.

TortoiseHg 2.0 introduces a dialog that makes this a little bit easier. If the shelve tool detects chunk rejections, it offers to open the rejected chunks in the rejects editor. The MQ tool also does this for qpush commands.

Resolve rejected patch chunks

The rejects editor is very basic. Your source file is opened in a QScintilla2 window for edit. Below the source file is the list of chunks that failed to apply to this file. When you click on a chunk in the list the editor jumps to the line where the chunk context was supposed to match. It is up to you to figure out why the chunk did not apply and to resolve it (perhaps even by ignoring the chunk). The resolved/unresolved states are for your own book keeping, so you know when all of the chunks have been dealt with. Once you have marked all of the chunks resolved, the Save button will become sensitive.

Extensions¶

This chapter describes Mercurial extensions that are shipped with TortoiseHg binary packages for Windows. These external extensions are included as a convenience to users, so they can be easily enabled as soon as they are needed.

Hgfold¶

hgfold is a Mercurial extension that helps Windows users deal with filename case collisions on VFAT and NTFS.

It adds options to the following Mercurial commands. Type hg help <command> for more information:

up    - allows you to update to a revision with filename collisions
merge - allows you to merge with a changeset that would create filename collisions

The extension does not currently do anything to prevent filename collisions. See discussion on the Mercurial Wiki

Installation

To test the use of this plugin, you can specify it on the Mercurial command line like this:

hg --config "extensions.fold=" status

You may want to add it to your Mercurial.ini or a repository’s hgrc like this:

[extensions]
fold=

If you do this, you can omit the –config command-line option.

Warnings

Like all merge operations, fold.py has to change the parents of the working directory. It is still in early testing, so use with caution.

If you get an error about an unknown changeset after running hg recover try hg debugsetparents <number of tip revision>. You can find the number of the tip revision by running hg log -l 2.

Perfarce¶

Perfarce home page.

This extension is documented in Perfarce (Perforce) section of Use with other VCS systems chapter.

Mercurial-Keyring¶

Mercurial Keyring home page
Keyring Extension wiki page

Keyring extension uses services of the keyring library to securely save authentication passwords (HTTP/HTTPS and SMTP) using system specific password database (Gnome Keyring, KDE KWallet, OSXKeyChain, dedicated solutions for Win32 and command line).

What it does

The extension prompts for the HTTP password on the first pull/push to/from given remote repository (just like it is done by default), but saves the password (keyed by the combination of username and remote repository url) in the password database. On the next run it checks for the username in .hg/hgrc, then for suitable password in the password database, and uses those credentials if found.

Similarly, while sending emails via SMTP server which requires authorization, it prompts for the password on first use of given server, then saves it in the password database and reuses on successive runs.

In case password turns out incorrect (either because it was invalid, or because it was changed on the server) it just prompts the user again.

Installation

First, the extension must be enabled in your Mercurial.ini file as:

[extensions]
mercurial_keyring=

Password backend configuration

The most appropriate password backend should usually be picked automatically, without configuration. Still, if necessary, it can be configured using ~/keyringrc.cfg file (keyringrc.cfg in the home directory of the current user). Refer to keyring docs for more details.

Note

On Windows XP and above, your encrypted passwords are stored in the credentials subsystem using CredRead and CredWrite

Note

On Windows 2K, the encrypted passwords are stored in the system registry under HKCU\Software\Mercurial\Keyring.

Repository configuration (HTTP)

Edit repository-local .hg/hgrc and save there the remote repository path and the username, but do not save the password. For example:

[paths]
myremote = https://my.server.com/hgrepo/someproject

[auth]
myremote.schemes = http https
myremote.prefix = my.server.com/hgrepo
myremote.username = mekk

Simpler form with url-embedded name can also be used:

[paths]
bitbucket = https://User@bitbucket.org/User/project_name/

Note

If both username and password are given in .hg/hgrc, extension will use them without using the password database. If username is not given, extension will prompt for credentials every time, also without saving the password. So, in both cases, it is effectively reverting to the default behaviour.

Consult [auth] section documentation for more details.

Repository configuration (SMTP)

Edit either repository-local .hg/hgrc, or ~/.hgrc (the latter is usually preferable) and set there all standard email and smtp properties, including smtp username, but without smtp password. For example:

[email]
method = smtp
from = Joe Doe <Joe.Doe@remote.com>

[smtp]
host = smtp.gmail.com
port = 587
username = JoeDoe@gmail.com
tls = true

Just as in case of HTTP, you must set username, but must not set password here to use the extension, in other cases it will revert to the default behaviour.

Usage

Configure the repository as above, then just pull and push (or email) You should be asked for the password only once (per every username + remote_repository_url combination).

projrc¶

projrc is an extension that makes Mercurial look for and parse .hg/projrc for additional configuration settings.The file is transferred on clone and on pull (but never on push), after confirmation by the user, from a list of servers that ‘’’must’’’ be configured by the user. For security reasons the user ‘’’must’’’ also select which ‘’projrc’’ configuration settings will be transferred (i.e. no settings are transferred from any servers by default). The user can also configure the extension to automatically accept all changes to the .hg/projrc file.

This is useful for centralized setups where you want to distribute configuration settings to all repositories with a minimum amount of setup. In particular, it can be used to remap subrepository sources, as explained on Mercurial’s SubrepoRemappingPlan.

Configuration

This extension (as most other extensions) is disabled by default. To use and configure you must first enable it on the Settings/Extensions panel.

When the extension is enabled you will see a new entry, “Projrc” on the settings dialog. This let’s you configure the extension by setting the following settings:

Request confirmation If True (the default) you’ll get a prompt whenever the extension detects changes to the remote server’s .hg/projrc file. If false, the extension will automatically accept any change to the remote .hg/projrc file.

Servers

This setting is a comma separated list of glob patterns matching the server names of the servers that the projrc file will be pulled from. Unless this setting is set, no .hg/projrc files will be ever transferred from any servers.

Include

This key lets you control which sections and which keys will be accepted from the remote projrc files. This is a a comma separated list of glob patterns that match the section or key names that will be included. Keys names must be specified with their section name followed by a ‘.’ followed by the key name (e.g. “’’diff.git’’”).

To allow all sections and all keys you can set this setting to “*” (without the quotes).

Exclude

This setting is similar to the “’’Include’’” setting but it has the opposite effect. It sets an “exclude list” of settings that will not be transferred from the common projrc files.

The exclude list has the same syntax as the include list. If an exclusion list is set but the inclusion list is empty or not set all non excluded keys will be included.

Update on incoming

Control whether the .hg/projrc file will be updated on incoming. It can have the following values:

never: The default. Show whether the remote projrc file has changed, but do not update (nor ask to update) the local projrc file.

prompt: Look for changes to the projrc file. If there are changes _always_ show a confirmation prompt, asking the user if it wants to update its local projrc file.

auto: Look for changes to the projrc file. Use the value of the “’’projrc.confirm’’” configuration key to determine whether to show a confirmation dialog or not before updating the local projrc file.

If False (the default) you’ll get a prompt whenever the extension detects changes to the remote server’s .hg/projrc file. If false, the extension will automatically accept any change to the remote .hg/projrc file.

If both an include and an exclude lists are set, and a key matches both the include and the exclude list, priority is given to the most explicit key match, in the following order:

full key, exact matches are considered the most explicit (e.g. “’’ui.merge’’”);

pattern (glob) matches are considered next (e.g. “’’auth.bitbucket.com.*’’”), with the longest matching pattern being the most explicit;

section level matches (e.g. “’’ui’’”);

global (”’’*’’”) matches.

If a key matches both an include and an exclude (glob) pattern of the same length, the key is ‘’included’’ (i.e. inclusion takes precedence over exclusion).

Usage

Once enabled and properly configured, the extension will look for .hg/projrc files whenever you clone or pull from one of the repositories specified on its “servers” configuration key.

Whenever the extension detects changes to the remote projrc file (e.g. when you do not have a .hg/projrc file yet, or when the contents of said file have changed on the server), you’ll receive a warning unless you have set the “Require confirmation” setting to False (in which case the extension assumes that you accept the changes). If you accept the changes your local .hg/projrc file will be updated, and its settings will be taken into account by mercurial and TortoiseHg.

If a local repository has a .hg/projrc file, you’ll see an extra panel on the setting dialog. The title of the extra panel is “project settings (.hg/projrc)”.

The “project settings” panel is a read-only panel that shows the settings that are set on the local .hg/projrc file. Although you can update your local version of the .hg/projrc file, the panel is read only to indicate that you cannot change the remote repository’s settings, and that if the remote repository settings change your local copy will be updated on the next pull (if you allow it).

The “project settings” settings panel is shown between the “global settings” panel and the “repository settings” panel, indicating that its settings are applied _after_ the global settings but _before_ the local repository settings (i.e the settings specified in the repository .hg/hgrc file).

Additional Information

For the most up to date information regarding this extension, to see several detailed usage examples and to learn how to use it and configure it from the command line, please go to the extension’s Wiki.

Use with other VCS systems¶

This chapter describes the three most popular Mercurial extensions for interoperating with foreign VCS systems. See also Repository Conversion

Perfarce (Perforce)¶

Perfarce home page.
Mercurial for Perforce users

This extension modifies the remote repository handling so that repository paths that resemble:

p4://p4server[:port]/clientname

cause operations on the named p4 client specification on the p4 server. The client specification must already exist on the server before using this extension. Making changes to the client specification Views causes problems when synchronizing the repositories, and should be avoided.

Five built-in Mercurial commands are overridden.

outgoing:

If the destination repository name starts with p4:// then this
reports files affected by the revision(s) that are in the local
repository but not in the p4 depot.

push:

If the destination repository name starts with p4:// then this
exports changes from the local repository to the p4 depot. If no
revision is specified then all changes since the last p4 changelist
are pushed. In either case, all revisions to be pushed are foled
into a single p4 changelist.  Optionally the resulting changelist is
submitted to the p4 server, controlled by the --submit option to
push, or by setting **perfarce.submit** to True.  If the option
**perfarce.keep** is False then after a successful submit the files
in the p4 workarea will be deleted.

pull:

If the source repository name starts with p4:// then this imports
changes from the p4 depot, automatically creating merges of
changelists submitted by hg push.  If the config option
**perfarce.keep** is False then the import does not leave files in
the p4 workarea, otherwise the p4 workarea will be updated with the
new files.

incoming:

If the source repository name starts with p4:// then this
reports changes in the p4 depot that are not yet in the local
repository.

clone:

If the source repository name starts with p4:// then this
creates the destination repository and pulls all changes from
the p4 depot into it.

The perfarce.tags configuration option determines whether perfarce tries to import Perforce labels as Mercurial tags.

TortoiseHg Integration

When the perfarce extension is enabled, it adds a start revision configurable option to the clone tool, and a P4 toolbar button to the sync tool.

The toolbar button performs the p4pending operation. It detects pending Perforce changelists that have been “push”ed to your Perforce client but have not been submitted, or have not been pulled back. This opens the pending changelist dialog so that you can view these pending changelists and either submit or revert them. If Perforce fails the submit because your files are out of date, you must revert the changelist, pull from Perforce, merge, then push again.

Installation

Perfarce comes bundled with TortoiseHg Windows installers, so you enable perfarce by simply adding it to your Mercurial.ini or a repository’s hgrc like this:

[extensions]
perfarce=

Note

The perfarce extension has been known to not work together with hgsubversion, so if you plan to use both extensions they should be enabled locally on the repositories that require them.

hgsubversion (SVN)¶

hgsubversion, as it’s name implies, allows you to use Mercurial as a client to a Subversion server. It can also be used to do straight conversions of Subversion repositories into Mercurial.

Installation

TortoiseHg Windows installers up to and including version 3.3.3 come with the python-svn bindings and hgsubversion included. Users of these versions can enable the hgsubversion extensions via the settings tool or manually:

[extensions]
hgsubversion =

You can verify that worked by typing hg help hgsubversion

Beginning with release 3.4 of TortoiseHg, the subversion libraries and the Python 2.7 SWIG bindings for them have been removed from the TortoiseHg packages. This was done primarily because of security problems in the subversion DLLs that we as TortoiseHg maintainers have no control over, but also to avoid having to package a second complete revision control system (SVN) in every copy of TortoiseHg (and the major headaches these bindings have become).

The python SWIG bindings are now provided as separate download. Instructions to download and use the python SWIG bindings is available at Subversion bindings for Python 2.7.

See the hgsubversion wiki for details of use. We recommend an hgsubversion version of at least 1.2.1 with Mercurial 1.8.

Warning

When cloning a Subversion server, it is highly recommended to clone only the first few revisions then pull the rest. The failure behavior of the clone command is to delete the incomplete clone, while pull is much more forgiving.

TortoiseHg Integration

Imported Subversion changesets will display the original Subversion checkin number in the Changeset Info widget in the Revision Details task tab of the Workbench.

hg-git (git)¶

hg-git, as its name implies, allows you to use Mercurial as a client to a git server. It can also be used to do straight conversions of Git repositories into Mercurial.

Installation

TortoiseHg Windows installers come with the python-git bindings (named dulwich) and hg-git. It can be enabled via the settings tool or manually:

[extensions]
hggit =

You can verify that worked by typing hg help hggit

See the hggit documentation for details of use.

Beware the ‘incoming’ command appears broken when speaking with git repositories, and ‘outgoing’ does not show much useful info. So you are restricted to simple push and pull commands, which is common with Mercurial extensions that speak to external revision control tools.

Frequently Asked Questions¶

What is TortoiseHg?

A Windows shell extension for the Mercurial revision control system, similar to the Tortoise clients for Subversion and CVS. It also includes a thg application for command line use on many platforms.

What comes included in the TortoiseHg binary installer for Windows?

Mercurial, kdiff3, TortoisePlink bonus extensions: hgfold, perfarce, mercurial-keyring. fixfrozenexts, python-svn for hgsubversion and convert extensions, and dulwich for hg-git use. See extension-versions.txt in the TortoiseHg folder for more details on the exact versions packaged.

Is Mercurial on Windows compatible with the index service and virus scanners?

No. Like TortoiseSVN, we recommend to turn off the indexing service on the working copies and repositories, and exclude them from virus scans.

How can I get translations for the Explorer context menu?

The available translations were stored by the installer under C:\Program Files\TortoiseHg\i18n\cmenu. Select the locale you would like to use, double-click on it, and confirm all requests.

How do I do merges and arbitrary version checkouts?

Merges and updates are intended to be done within the Workbench, using changeset context menus

Why can’t I connect to an ssh server (remote: bash: <server name>: command not found)?

TortoisePlink (and basic Plink) will try to use the Host Name configured in Putty under the Default Settings. It adds this host name to its command line parameters, causing the hostname to be specified twice, causing this particular error. Clearing the host name from the Default Settings is a possible workaround.

How can I use tool X as my visual diff tool?

Since version 1.0, TortoiseHg should autodetect most popular visual diff tools and make them available for selection from the Visual Diff Tool item in the settings tool.

How is TortoiseHg configured?

TortoiseHg gets configuration settings from two systems.

The Mercurial configuration system, which is three-tiered

Site-wide Mercurial.ini in %ProgramFiles%\TortoiseHg

Per-User Mercurial.ini in %UserProfile%

Per-Repository hgrc in repo-root\.hg

The folder %APPDATA%\TortoiseHg:

File thg-reporegistry.xml holds the content of the RepoRegistry.

File TortoiseHgQt.ini contains the settings for application state (window positions, etc).

These are some of the configurables that are stored in the Mercurial configuration system.
[tortoisehg]
vdiff = vdiff
editor = gvim
tabwidth = 4
longsummary = True
authorcolor = True
authorcolor.steve = blue

Where do TortoiseHg extensions look for external Python modules on Windows?

TortoiseHg includes an entire Python distribution bundled up as DLLs. The standard library modules are all in the library.zip file in C:\Program Files\TortoiseHg.

If you try to use an extension that imports a non-standard Python module, you will find that the extension will fail to load because it can’t find the module. For example the ReviewBoard extension imports the simplejson module, which is not part of the standard Python distribution.

In order to make it work you need to add a couple of lines to the top of the extension’s .py file, before the line that imports the foreign module:
import sys
sys.path.append(r'C:\path\to\module')
Note that this will not work for modules distributed as .egg files; the supplied path must contain the module’s .py or .pyc files.

If you have many extensions and/or hooks that all share the same Python package, you can create an extension which explicitly modifies sys.path for all the others. Simply name the extension such that it is loaded first (alphabetically). Something like:
[extensions]
00setSysPath = C:\path\to\setsyspath.py

Debugging¶

Dialogs¶

Stderr is being captured to a buffer that is being inspected at program exit. If any serious errors (tracebacks, etc) are found in the stderr buffer the entire contents are sent to the bug report tool so the user can (should) report a bug. If you suspect there are errors that are not being reported, you can set the environment variable THGDEBUG to any value to disable the stderr buffering.

If you have a bit of Python knowledge, you can also use:

thg --debugger <command>

To disable the forking behavior of thg, you can either set an environment variable THG_HGTK_SPAWN, or add the command line parameter ‘–nofork’.

Windows¶

To debug the changelog viewer, for instance, enter these commands into a cmd.exe window, while inside the repository:

set THGDEBUG=1
thg --nofork log

Linux/MacOSX¶

To debug the changelog viewer, for instance, enter these commands into your shell window, while inside the repository:

export THGDEBUG=1
thg --nofork log

Shell Extension¶

The debugging mechanisms depend on your platform.

Windows¶

See also https://msdn.microsoft.com/en-us/library/cc144064(VS.85).aspx for some info bits about Running and Testing Shell Extensions on Windows

The DbgView tool from the SysInternals suite will capture debug messages from the shell extension. However, the shell extension does not emit debugging info by default. It must be enabled by setting the registry key defined in win32/shellext/DebugShellExt.reg in the TortoiseHg source repository. You can double-click on this file to load the key into your registry.

Another option is to exit the TortoiseHgOverlayServer system tray application and start it from the command line. It will emit some debug information to the console.

Nautilus¶

Debugging is done via the environment variable DEBUG_THG

to test in a separate process:

DEBUG_THG=Ne TMPDIR=/tmp/anydir/ --no-desktop nautilus [path]

to test in the main instance:
```
nautilus -q
DEBUG_THG=NOe nautilus
```
permanent debugging, set DEBUG_THG in a file which is read on session start (~/.profile, ~/.xprofile)

Upper case characters in DEBUG_THG specify modules. Only O and N for OverlayCache and Nautilus, respectively, are supported module names. Lower case characters imply parts. Only e is supported, implying error messages.

To restart nautilus, chose either

killall nautilus (the session restarts nautilus automatically, stdin and stdout go to ~/.xsession-errors)
nautilus -q; nautilus (stdin and stdout are on the console)

Welcome to TortoiseHg’s documentation!¶

Preface¶

Audience¶

Reading guide¶

TortoiseHg is free!¶

Community¶

Acknowledgements¶

Conventions used in this manual¶

Introduction¶

What is TortoiseHg?¶

Installing TortoiseHg¶

On Windows¶

Language settings¶

On Linux and Mac¶

What’s New¶

TortoiseHg 2.0¶

Philosophy¶

Workbench¶

Showing Mercurial command lines¶

Resolve tool, deliberate merges¶

Shelve Improved¶

Revision Sets¶

Technology¶

Qt and PyQt¶

QScintilla2¶

Polling of repository state and config¶

Immediate bug report dialogs¶

Demand loaded graph¶

A Quick Start Guide to TortoiseHg¶

Configuring TortoiseHg¶

Getting Acquainted¶

Initialize the repository¶

Add files¶

Ignore files¶

Commit¶

Share the repository¶

Fetching from the group repository¶

Working with your repository¶

TortoiseHg in daily use¶

Common Features¶

Visual Diffs¶

Adding Tools¶

Word Diffs¶

Windows Explorer Integration¶

Context Menus¶

Overlay Icons¶

Shell Configuration¶

GNOME desktop integration¶

Workbench¶

Workbench Menus¶

Edit Toolbar¶

Dock Toolbar¶

Sync Toolbar¶

Task Toolbar¶

Filter Toolbar¶

Revision Graph Details¶

Performance Implications¶

Revision Context Menus¶

File Context Menus¶

Message Parsing¶

Output Log Console¶

Keyboard navigation¶

Configurables¶

From command line¶

Create a new repository¶

From command line¶

Clone a repository¶

From command line¶

Commit¶

Features¶

Change Selection¶

Keyboard navigation¶

File Context Menus¶

Merging¶

Commit Message Pane¶

Subrepositories¶

Configurables¶

From command line¶

Shelve¶

Features¶