**********
Extensions
**********

.. module:: extensions
	:synopsis: Describe extensions bundled with TortoiseHg binary packages

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 <https://www.mercurial-scm.org/wiki/CaseFoldExtension>`_ 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
:command:`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
:command:`hg recover` try
:command:`hg debugsetparents <number of tip revision>`.
You can find the number of the tip revision by running :command:`hg log -l 2`.

Perfarce
========

`Perfarce <http://www.kingswood-consulting.co.uk/hg/perfarce/>`_ home
page.

This extension is documented in :ref:`perfarce-perforce` section of
:doc:`nonhg` chapter.

Mercurial-Keyring
=================

* `Mercurial Keyring <https://pypi.python.org/pypi/mercurial_keyring>`_ home page
* `Keyring Extension <https://www.mercurial-scm.org/wiki/KeyringExtension>`_ 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 :file:`.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
:file:`~/keyringrc.cfg` file (:file:`keyringrc.cfg` in the home directory of
the current user).
Refer to `keyring docs <https://pypi.python.org/pypi/keyring>`_
for more details.

.. note::
	On Windows XP and above, your encrypted passwords are stored in the
	credentials subsystem using
	`CredRead <https://msdn.microsoft.com/en-us/library/aa374804%28VS.85%29.aspx>`_ and `CredWrite <https://msdn.microsoft.com/en-us/library/aa375187%28VS.85%29.aspx>`_

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

**Repository configuration (HTTP)**

Edit repository-local :file:`.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 :file:`.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] <https://www.mercurial-scm.org/doc/hgrc.5.html#auth>`_
section documentation for more details.

**Repository configuration (SMTP)**

Edit either repository-local :file:`.hg/hgrc`, or :file:`~/.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).

.. vim: noet ts=4

projrc
======

`projrc <https://www.mercurial-scm.org/wiki/ProjrcExtension>`_ 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 <https://www.mercurial-scm.org/wiki/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:

	:guilabel:`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.

    :guilabel:`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.

    :guilabel:`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).

    :guilabel:`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.

    :guilabel:`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 <https://www.mercurial-scm.org/wiki/ProjrcExtension>`_.

pbranch
=======

Patch Branches (`pbranch <https://www.mercurial-scm.org/wiki/PatchBranchExtension>`_)
is a way to develop a series of patches for submission into a main
repo. It is based on topic branches, one per patch, and is thus highly
suitable for collaborative and/or long-term patch development and
maintenance.

`A detailed manual <http://arrenbrecht.ch/mercurial/pbranch/>`_ can be found online.

It adds a number of commands which can be listed with
:command:`hg help pbranch`::

 pbackout       - backs out the current patch branch (undoes all its changes)
 pdiff          - prints the final diff for the current or given patch branch
 peditmessage   - edit the patch message
 pemail         - send patches by email
 pexport        - exports patches
 pextdiff       - combines pdiff and extdiff
 pgraph         - print an ASCII art rendering of the patch dependency graph
 pmerge         - merge pending heads from dependencies into patch branches
 pmessage       - print the patch message(s)
 pnew           - start a new patch branch
 pstatus        - print status of current (or given) patch branch
 reapply        - reverts the working copy of all files touched by REV to REV

TortoiseHg will provide a new task tab that shows the patch dependency graph.

 .. figure:: figures/pbranch.png
	:alt: Pbranch task tab

	Pbranch task tab


**Installation**

As this extension is not installed with TortoiseHg, you have to download
it from `<https://bitbucket.org/parren/hg-pbranch>`_. Be sure to dowload the
right one according to the Mercurial version included with TortoiseHg (see the
wiki page on the download site).
To test the use of this plugin, you can specify it on the Mercurial
command line like this::

	hg --config "extensions.pbranch=C:\path\to\pbranch.py" pstatus

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

	[extensions]
	pbranch = C:\path\to\pbranch.py

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