6. Settings

Settings dialog

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.

  1. A site-wide configuration file in C:\Program Files\TortoiseHg\Mercurial.ini This file is read first and thus has the lowest priority.
  2. 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.
  3. 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.

6.1. 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).

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

6.1.2. 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 and pbranch. Default: log commit grep pbranch | 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.

6.1.3. 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 showed. 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 showed. If False, selected deleted files will be included in the commit with no confirmation dialog. Default: True

6.1.4. 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)

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

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

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

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

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

6.1.10. 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 IBugTrackProvider2 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}

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

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

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

6.1.14. GnuPG

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

6.2. Keyboard navigation

Ctrl-Enter
Apply changes and close the tool, the equivalent of pressing the ‘Ok’ button.

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