4.1. Common Features

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

4.1.1. Keyboard Accelerators

We define a few keyboard accelerators that all of the TortoiseHg tools support.

Ctrl-Q
quit the application, including all open windows
Ctrl-W
close the current window (same as Ctrl-Q if only one window is open)
Ctrl-D
visual diff of currently selected file or changeset
Ctrl-Enter
activation
Ctrl-. and Ctrl-,
select next or previous file in a file list
Ctrl-[ and Ctrl-]
page up or down a text pane
F5, Ctrl-R
refresh

On Mac OS X, the apple (command) key is used as the modifier instead of Ctrl. However some keyboard accelerators are internal to GTK+ so you must use the control key to access cut-paste functionality, for instance.

4.1.2. Visual Diffs

Visual Diff Window

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:

  1. The selection of files being compared require multiple tools
  2. The selected tool forks detached background processes
  3. The selected tool does not support the required directory diffs
  4. The selected tool does not support three way comparisons
  5. 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.

Note

The TortoiseHg ‣ Skip Diff Window configurable has been removed because it is now redundant.

4.1.2.1. 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
$ancestor: the file or directory from the ancestor of a merge
$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
$alabel:   a symbolic name for the ancestor revision

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.

4.1.2.2. 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.

4.1.3. Treeview searches

Many TortoiseHg dialogs use treeviews to present lists of data to the user. The file lists in the status, commit, shelve, and changelog tools are treeviews. The changelog graph pane is a treeview. And even the annotate pane in the datamine tool is a treeview.

Most of the TortoiseHg treeviews are configured for live searches. Ensure that the treeview has focus (by clicking on a row), and begin typing a search phrase. A small entry window will appear containing the text you have typed, and the treeview will immediately jump to the first row that matches the text you have entered thus far. As you enter more characters, the search is refined. (Do not hit return to ‘complete’ the search, before using the keys mentioned below, or the entry window will disappear, ending the search instead.)

  • Ctrl-F opens the search window explicitly
  • Ctrl-G advances the search to the next match
  • Shift-Ctrl-G searches backwards
  • The mouse scroll wheel will advance forwards and backwards through matching lines

4.1.4. Hg command dialog

Many TortoiseHg tools use the hgcmd dialog to execute Mercurial commands that could potentially be interactive.

Mercurial command dialog

Interactive Mercurial Command Dialog

Note

Error messages are given a dark red color for contrast

When the Mercurial command has completed, the dialog gives focus to its Close button. So pressing Enter is all that is required to close the window.