#pragma section-numbers 2

= Keyring Extension =

'''This extension is not distributed with Mercurial.'''

''Author: Marcin Kasperski''

Project site: http://pypi.python.org/pypi/mercurial_keyring

Repository: https://foss.heptapod.net/mercurial/mercurial_keyring/

''For the most up to date and more complete documentation see  [[https://foss.heptapod.net/mercurial/mercurial_keyring/|this description]].''
or, equivalently (but with worse formatting) [[http://pypi.python.org/pypi/mercurial_keyring|copy on PyPi]]


(!) If you are on Windows, we recommend you use TortoiseHg.  It ships with Windows-specific keyring backends, without
which the mercurial-keyring extension cannot function properly on Windows.
The mercurial-keyring extension itself has been shipped with TortoiseHg since version 0.10.

<<TableOfContents>>

== Overview ==

Keyring extension uses services of the [[http://pypi.python.org/pypi/keyring|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 the password turns out incorrect (either because it was invalid,
or because it was changed on the server) it just prompts the user
again.

== Installation ==

Install the keyring library:

{{{
easy_install keyring
}}}

(or use any other method to install it [[http://pypi.python.org/pypi/keyring|from PIP]]).
On Debian "Sid" the library can be also installed from the official archive (packages ''python-keyring'',
''python-keyring-gnome'' and ''python-keyring-kwallet'').

Then use one of the two options:

a) Install `mercurial_keyring` as a module from PyPi:

{{{
easy_install mercurial_keyring
}}}

and configure your ''`.hgrc`'' so:

{{{
[extensions]
mercurial_keyring =
}}}

b) Download [[http://bitbucket.org/Mekk/mercurial_keyring/raw/default/mercurial_keyring.py]],
save this file anywhere on the system (preferably in hgext directory), and
configure your ''`.hgrc`'' to enable the extension by adding following lines:

{{{
[extensions]
hgext.mercurial_keyring = /path/to/mercurial_keyring.py
}}}

== Configuration ==

=== 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 [[http://pypi.python.org/pypi/keyring|keyring docs]] for more details.

=== 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 the username and password are given in ''`.hg/hgrc`'', the extension
will use them without using the password database. If the 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.

=== 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) as needed.
You should be asked for the password only once (per every username+remote_repository_url combination).

----
CategoryExtensionsByOthers