Package: mercurial_keyring
Mercurial Keyring is aMercurialextension used to securely save HTTP
and SMTP authentication passwords in password databases (Gnome
Keyring, KDE KWallet, OSXKeyChain, Windows Vault etc).Withmercurial_keyringactive, Mercurial remembers your passwords
and reuses them without prompting (as if you stored them in.hgrc),
but password storage is reasonably secure.Actual password storage is implemented by thekeyringlibrary, this
extension glues it to Mercurial.1How does it work2Installation2.1Prerequisites2.2Extension installation3Password backend configuration4hgrcconfiguration (HTTP)4.1Repository level configuration4.2Account-level configuration5hgrcconfiguration (SMTP)6Usage6.1Saving and restoring passwords6.2Checking password status (hg keyring_check)6.3Deleting saved password (hg keyring_clear)6.4Managing passwords using GUI tools7Implementation details8Frequent problems9History10Repository, bug reports, enhancement suggestions11Additional notes1How does it workOn 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_keyringchecks 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_keyringprompts
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.2Installation2.1PrerequisitesThis extension requireskeyringandmercurial_extension_utilsto
work. In many cases both will be installed automatically while you
installmercurial_keyring, but you may need to control the process.Thekeyringlibrary can usually be installed by:pip install --user keyring(oreasy_install keyring), but on some systems it is preferable to
use official distribution archive. For example, on Debian and Ubuntu,
you may installpython-keyringand eitherpython-keyring-gnomeorpython-keyring-kwalletpackages:sudo apt-get install python-keyring python-keyring-gnome(this will save you the need to provide working compiler and various
development libraries).Themercurial_extension_utilsmodule is tiny Python-only module,
which can be installed by:pip install --user mercurial_extension_utilsbut in some cases (Windows…) requires more care. Seemercurial_extension_utilsdocumentation.2.2Extension installationThere are two possible ways of installing the extension: using PyPi package,
or using source clone.To install as a package:pip install --user mercurial_keyring(orsudo pip install mercurial_keyringfor system-wide
installation) and then enable it in~/.hgrc(or/etc/mercurial/hgrcorMercurial.ini) using:[extensions]
mercurial_keyring =To install using source clone, installkeyringaccording to the
instructions above, then clone:hg clone https://foss.heptapod.net/mercurial/mercurial_keyring/
hg clone https://foss.heptapod.net/mercurial/mercurial-extension_utils/and configure Mercurial using  full path to the extension module:[extensions]
mercurial_keyring = /path/to/mercurial_keyring/mercurial_keyring.py3Password backend configurationThe 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
usingkeyringrc.cfgfile.  Refer tokeyringdocs for more
details.NoteWith current (as I write) keyring (5.6), this file is (on Linux)
located at~/.local/share/python_keyring/keyringrc.cfgand
it’s example content looks like:[backend]
default-keyring=keyring.backends.Gnome.Keyring
# default-keyring=keyring.backends.kwallet.KeyringFor list of known backends runpydoc keyring.backendsorkeyring--list-backends(which of those commands work,
depends on thekeyringversion).4hgrcconfiguration (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 usernamemercurial_keyringcan’t save or restore
passwords, so it disables itself.Without url prefixmercurial_keyringworks, 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).4.1Repository level configurationEdit repository-local.hg/hgrcand 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.prefix = https://my.server.com/hgrepo
myremote.username = JohnSimpler form with url-embedded name can also be used:[paths]
bitbucket = https://John@my.server.com/hgrepo/someproject/but is not recommended.Note that all repositories sharing the sameprefixshare the same
password.Mercurial allows also for password in.hg/hgrc(either given by«prefix».password, or embedded in url). If such password is found,
Mercurial Keyring disables itself.4.2Account-level configurationIf you are consistent about remote repository nicknames, you can
configure the username in your~/.hgrc(.hgrcin your home
directory). For example, write there:[auth]
acme.prefix = hg.acme.com/repositories
acme.username = johnny
acme.schemes = http https
heptapod.prefix = https://foss.heptapod.net
heptapod.username = Mekk
mydep.prefix = https://dev.acmeorg.com
mydep.username = drmartinand as long as you useacmealias for repositories likehttps://hg.acme.com/repositories/my_beautiful_app, usernamejohnnywill be used, and the same password reused. Similarly
anyhg push heptapodwill assume usernameMekkand share
the same password.With such config repository-level.hg/hgrcneed only contain[paths].Additional advantage of this method is that it works also duringclone.NoteMercurial Keyring works well withPath Pattern. On my setup I use
prefix as above, and:[path_pattern]
heptapod.local = ~/devel/mercurial/{below}
heptapod.remote = https://foss.heptapod.net/mercurial/{below:/=-}so all my repositories understandhg push bitbucketwithout
any repository-level configuration.5hgrcconfiguration (SMTP)Edit either repository-local.hg/hgrc, or~/.hgrcand 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 = trueJust as in case of HTTP, youmustset username, butmust notset
password here to use the extension, in other cases it will revert to
the default behavior.6Usage6.1Saving and restoring passwordsConfigure the repository as above, then justhg pull,hg push,
etc.  You should be asked for the password only once (per every
username and remote repository prefix or url combination).Similarly, for email, configure as above and justhg email.
Again, you will be asked for the password once (per every username and
email server address combination).6.2Checking password status (hg keyring_check)Thekeyring_checkcommand can be used to check whether/which
password(s) are saved. It can be used in three ways:without parameters, it prints info related to all HTTP paths
defined for current repository (everything fromhg pathsthat resolves to HTTP url):hg keyring_checkgiven alias as param, it prints info about this alias:hg keyring_check workfinally, any path can be checked:hg keyring_check https://foss.heptapod.net/mercurial/mercurial_keyring6.3Deleting saved password (hg keyring_clear)Thekeyring_clearcommand removes saved password related to given
path. It can be used in two ways:given alias as param, it drops password used by this alias:hg keyring_clear workgiven full path, it drops password related to this path:hg keyring_clear https://foss.heptapod.net/mercurial/mercurial_keyring6.4Managing passwords using GUI toolsMany password backends provide GUI tools for password management,
for example Gnome Keyring passwords can be managed usingseahorse,
and KDE Wallet usingkwalletmanager. Those GUI tools can be used
to review, edit, or delete saved passwords.Unfortunately, as I write,keyringlibrary does not allow one to
configure how/where exactly saved passwords are put in the hierarchy,
and the place is not always intuitive. For example, in KDE Wallet, all
passwords saved usingmercurial_keyringshow up in the folder
namedPython.NoteThis is slightly problematic in casemercurial_keyringis not
the only program usingkeyringlibrary. Passwords saved by another
Python application or script (which also useskeyring) will be put
into the same place, and it may be unclear which password belongs
to which program. To remedy this,mercurial_keyringapplies
slightly unusual labels of the form«username»﻿@@﻿«urlprefix»﻿@﻿Mercurial- for example my bitbucket
password is labelledMekk﻿@@﻿https﻿://﻿bitbucket.org﻿@﻿Mercurial.7Implementation detailsThe extension is monkey-patching the mercurialpasswordmgrclass
to replace thefind_user_passwordmethod. Detailed order of operations
is described in the comments insidethe code.8Frequent problemsMost problems people face while usingmercurial_keyringare in
fact problems withkeyringlibrary and it’s backends. In
particular, those can manifest by:technical errors mentioning sentences likeNo recommended backend was available. Install the keyrings.alt package…(or similar),warnings likekeyring: keyring backend doesn't seem to work…password prompts on every action (= passwords not being saved).Those almost always mean thatnaturalkeyring 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 duringkeyringlibrary 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 usingkeyringutility, as described
onkeyringdocumentation 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 thekeyringcommand
as such, trypython-mkeyringinstead: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 testuserIf appropriate backend is missing (not listed), or doesn’t work
(second or third command fails), your keyring is broken. Try looking
for further pointers inkeyringdocumentation, 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.NoteDepending onkeyringversion, installation of some dependency may
resolve problem. For example (as of late 2018), I got KDE Wallet
backend working with pip-installed keyring after:pip install dbus-pythonNote also, that recent versions of keyring library (since version 12) use Python
entrypoints to find available backends. Those are incompatible with
some binary packaging methods (likepy2app) and may cause
problems. In particular there were packaged installations ofTortoiseHGwhich were unable to load keyring backends. See#61for some more details.Ifkeyringcommand works, but mercurial with mercurial_keyring does not,
try enforcing  proper backend (by means ofkeyringrc.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 (likepython-keyringUbuntu package, or keyring
bundled withTortoiseHGon some systems). If you pip-installed keyring
and it doesn’t work, you may consider removing it viapip uninstall keyringand looking for binary package instead.9HistorySeeHISTORY.rst.10Repository, bug reports, enhancement suggestionsDevelopment is tracked on HeptaPod, seehttps://foss.heptapod.net/mercurial/mercurial_keyring/Use issue tracker there for bug reports and enhancement
suggestions.Thanks toOctobusandClever Cloudfor hosting this service.11Additional notesInformation about this extension is also available
on Mercurial Wiki:https://www.mercurial-scm.org/wiki/KeyringExtensionCheck alsoother Mercurial extensions I wrote.