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

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

8.2. Perfarce¶

Perfarce home page.

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

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

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