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

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

5.1.1. TortoiseHg

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 Command:
Specify visual diff tool; must be an extdiff command.
Skip Diff Window:
Bypass the builtin visual diff dialog and directly use your visual diff tool’s directory diff feature. Only enable this feature if you know your diff tool has a valid extdiff configuration. Default: False.
Visual Editor:
Specify the visual editor used to view files, etc.
CLI Editor:
The editor to use during a commit and other instances where Mercurial needs multiline input from the user. Only used by command line interface commands.
Tab Width:
Specify the number of spaces that tabs expand to in various TortoiseHg windows. Default: Not expanded.
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).
Bottom Diffs:
Show the diff panel below the file list in status, shelve, and commit dialogs. Default: False (show diffs to right of file list).
Capture Stderr:
Redirect stderr to a buffer which is parsed at the end of the process for runtime errors. Default: True.
Fork hgtk:
When running hgtk 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
Spell Check Language:
Default language for spell check. System language is used if not specified. Examples: en, en_GB, en_US. Spell checking requires gtkspell, which is only available on Gnome PCs.

5.1.2. Commit

Username:
Name associated with commits.
Summary Line Length:
Maximum length of the commit message summary line. If set, TortoiseHg will issue a warning if the summary line is too long or not separated by a blank line. Default: 0 (unenforced).
Message Line Length:
Word wrap length of the commit message. If set, the popup menu can be used to format the message and a warning will be issued if any lines are too long at commit. Default: 0 (unenforced).
Push After Commit:
Attempt to push to default push target after every successful commit. Default: False
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
Auto Exclude List:
Comma separated list of files that are automatically unchecked when the status, commit, and shelve dialogs are opened. Default: None

5.1.3. Changelog

Author Coloring:
Color changesets by author name. If not enabled, the changes are colored green for merge, red for non-trivial parents, black for normal. Default: False.
Long Summary:
If true, concatenate multiple lines of changeset summary until they reach 80 characters. Default: False.
Log Batch Size:
The number of revisions to read and display in the changelog viewer in a single batch. Default: 500.
Copy Hash:
Allow the changelog viewer to copy the changeset hash of the currently selected changeset into the clipboard. DEPRECATED, will be removed in a later release. Default: False.
Dead Branches:
Comma separated list of branch names that should be ignored when building a list of branch names for a repository. Default: None
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 @ character, and \n to a linefeed. Default: None
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.

5.1.4. Sync

The Sync tab is where you can store URLs (paths) to related repositories. It is rare to store paths in the site-wide or user configuration files, most of the time you will only store these in a repository configuration file. Mercurial has two special path names that can be used as default targets for some operations.

  • default - the default URL to pull from, usually clone source
  • default-push - the default push target when using the command line
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. Default: none.
Remote repository paths
In this pane you can configure aliases for repositories that you frequently synchronize with. Mercurial will add a default alias to the clone source automatically. All configured path aliases will be listed in the Synchronize tool path drop-down box, and they can be used as short-cuts on the command line.

5.1.5. Web

Name:
Repository name to use in the web interface. Default is the working directory.
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.
Encoding:
Character encoding name.

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

5.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:
Connect to mail server using TLS. Default: False.
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.

5.1.8. Diff

Patch EOL:
Normalize file line endings during and after patch to lf or crlf. Strict does no normalization. Default: strict
Git Format:
Use git extended diff header format. Default: False.
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.

5.2. Keyboard navigation

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

5.3. From command line

The setting dialog can be started from command line

hgtk repoconfig

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

hgtk userconfig

for the user configuration (Mercurial.ini file).

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