1   How does it work

On your first pull or push to HTTP url (or first email sent via given SMTP server), you are prompted for the password, just like bare Mercurial does. But the password you entered is saved to appropriate password database. On successive runs, whenever the password is needed, mercurial_keyring checks for password in password database, and uses it without troubling you.

In case password turns out to be incorrect (for example, because you changed it, or entered it incorrectly), mercurial_keyring prompts you again, and overwrites the password.

You can use many passwords (for various remote urls). Saved passwords are identified by pair of username and url prefix. See below for information how to configure those properly.

2   Installation

pip install --user keyring

sudo apt-get install python-keyring python-keyring-gnome

pip install --user mercurial_extension_utils

pip install --user mercurial_keyring

[extensions]
mercurial_keyring =

hg clone https://foss.heptapod.net/mercurial/mercurial_keyring/
hg clone https://foss.heptapod.net/mercurial/mercurial-extension_utils/

[extensions]
mercurial_keyring = /path/to/mercurial_keyring/mercurial_keyring.py

3   Password backend configuration

The most appropriate password backend should usually be picked without configuration (considering installed libraries, operating system, active desktop session). Still, if necessary, it can be configured using keyringrc.cfg file. Refer to keyring docs for more details.

[backend]
default-keyring=keyring.backends.Gnome.Keyring
# default-keyring=keyring.backends.kwallet.Keyring

4   hgrc configuration (HTTP)

Mercurial Keyring uses standard Mercurial [auth] configuration to detect your username (on given remote) and url prefix. You are strongly advised to configure both.

Without the username mercurial_keyring can't save or restore passwords, so it disables itself.

Without url prefix mercurial_keyring works, but binds passwords to repository urls. That means you will have to (re)enter password for every repository cloned from given remote (and that there will be many copies of this password in secure storage).

[paths]
myremote = https://my.server.com/hgrepo/someproject

[auth]
myremote.prefix = https://my.server.com/hgrepo
myremote.username = John

[paths]
bitbucket = https://John@my.server.com/hgrepo/someproject/

[auth]
acme.prefix = hg.acme.com/repositories
acme.username = johnny
acme.schemes = http https
bitbucket.prefix = https://bitbucket.org
bitbucket.username = Mekk
mydep.prefix = https://dev.acmeorg.com
mydep.username = drmartin

[path_pattern]
bitbucket.local = ~/devel/{below}
bitbucket.remote = https://bitbucket.org/Mekk/{below:/=-}

5   hgrc configuration (SMTP)

Edit either repository-local .hg/hgrc, or ~/.hgrc 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 behavior.

6   Usage

7   Implementation details

The extension is monkey-patching the mercurial passwordmgr class to replace the find_user_password method. Detailed order of operations is described in the comments inside the code.

8   Frequent problems

Most problems people face while using mercurial_keyring are in fact problems with keyring library and it's backends. In particular, those can manifest by:

• technical errors mentioning sentences like No recommended backend was available. Install the keyrings.alt package… (or similar),
• warnings like keyring: keyring backend doesn't seem to work…
• password prompts on every action (= passwords not being saved).

Those almost always mean that natural keyring backend for given desktop type doesn't work, or is not present at all. For example, some necessary runtime component can be down (say, you use Linux, but neither Gnome Keyring, nor KDE Wallet, is running). Or appropriate backend is not installed because it could not be build during keyring library installation (maybe because some required library was not present at the moment of keyring installation, or maybe because compiler as such is not present on the system).

To diagnose such problems, try using keyring utility, as described on keyring documentation page, for example by:

keyring --list-backends
keyring -b keyrings.alt.Gnome.Keyring set testsvc testuser
keyring -b keyrings.alt.Gnome.Keyring get testsvc testuser

(of course using appropriate backend). If you miss the keyring command as such, try python -m keyring instead:

python -m keyring --list-backends
python -m keyring -b keyrings.alt.Gnome.Keyring set testsvc testuser
python -m keyring -b keyrings.alt.Gnome.Keyring get testsvc testuser

If appropriate backend is missing (not listed), or doesn't work (second or third command fails), your keyring is broken. Try looking for further pointers in keyring documentation, that project mailing list, or issue tracker. Typically it will turn out, that you need to install some missing tool, or library, and reinstall keyring.

pip install dbus-python

If keyring command works, but mercurial with mercurial_keyring does not, try enforcing proper backend (by means of keyringrc.cfg, see above). Only if this doesn't help, there may be a bug in mercurial_keyring.

By far easiest way to have properly working keyring is to use packaged binary version (like python-keyring Ubuntu package, or keyring bundled with TortoiseHG on some systems). If you pip-installed keyring and it doesn't work, you may consider removing it via pip uninstall keyring and looking for binary package instead.

9   History

See HISTORY.rst.

10   Repository, bug reports, enhancement suggestions

Development is tracked on HeptaPod, see https://foss.heptapod.net/mercurial/mercurial_keyring/

Use issue tracker there for bug reports and enhancement suggestions.

Thanks to Octobus and Clever Cloud for hosting this service.

11   Additional notes

Information about this extension is also available on Mercurial Wiki: https://www.mercurial-scm.org/wiki/KeyringExtension

Check also other Mercurial extensions I wrote.