README.txt
174 lines
| 4.8 KiB
| text/plain
|
TextLexer
|
r37 | .. -*- mode: rst -*- | ||
|
r35 | |||
================= | ||||
mercurial_keyring | ||||
================= | ||||
|
r37 | ``mercurial_keyring`` is a Mercurial_ extension used to securely save | ||
HTTP and SMTP authentication passwords in password databases (Gnome | ||||
|
r36 | Keyring, KDE KWallet, OSXKeyChain, specific solutions for Win32 and | ||
command line). This extension uses and wraps services of the keyring_ | ||||
library. | ||||
|
r35 | |||
.. _keyring: http://pypi.python.org/pypi/keyring | ||||
|
r36 | .. _Mercurial: http://mercurial.selenic.com | ||
|
r35 | |||
How does it work | ||||
================ | ||||
The extension prompts for the password on the first pull/push (in case | ||||
of HTTP) or first email (in case of SMTP), just like it is done by | ||||
|
r37 | default, but saves the password. On successive runs it checks for the | ||
username in ``.hg/hgrc``, then for suitable password in the password | ||||
database, and uses those credentials (if found). | ||||
|
r35 | |||
In case password turns out to be incorrect (either because it was | ||||
|
r36 | invalid, or because it was changed on the server) or missing it just | ||
prompts the user again. | ||||
|
r35 | |||
|
r37 | Passwords are identified by the combination of username and remote | ||
repository url (for HTTP) or username and smtp server address (for | ||||
SMTP), so they can be reused between repositories if they access | ||||
the same remote repository. | ||||
|
r35 | Installation | ||
============ | ||||
|
r36 | Prerequisites | ||
------------- | ||||
Install the keyring_ library: | ||||
|
r35 | |||
:: | ||||
easy_install keyring | ||||
(or ``pip keyring``). On Debian "Sid" the library can be also | ||||
|
r36 | installed from the official archive (packages ``python-keyring`` | ||
and either ``python-keyring-gnome`` or ``python-keyring-kwallet``). | ||||
Extension installation | ||||
---------------------- | ||||
There are two possible ways of installing the extension: using PyPi package, | ||||
or using individual file. | ||||
To install as a package use ``easy_install``: | ||||
|
r35 | |||
|
r36 | :: | ||
easy_install mercurial_keyring | ||||
|
r37 | and then enable it in ``~/.hgrc`` (or ``/etc/mercurial/hgrc``) using: | ||
|
r35 | |||
|
r36 | :: | ||
[extensions] | ||||
mercurial_keyring = | ||||
To install using individual file, download the | ||||
|
r37 | `mercurial_keyring.py`_ file, save it anywhere you like, and | ||
|
r35 | put the following in ``~/.hgrc`` (or ``/etc/mercurial/hgrc``): | ||
:: | ||||
[extensions] | ||||
hgext.mercurial_keyring = /path/to/mercurial_keyring.py | ||||
|
r37 | .. _the code: | ||
.. _mercurial_keyring.py: http://bitbucket.org/Mekk/mercurial_keyring/src/tip/mercurial_keyring.py | ||||
|
r35 | Password backend configuration | ||
============================== | ||||
The library should usually pick the most appropriate password backend | ||||
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. | ||||
|
r37 | *I considered handling similar options in hgrc, but decided that | ||
|
r35 | single user may use more than one keyring-based script. Still, I am | ||
|
r37 | open to suggestions.* | ||
|
r35 | |||
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. | ||||
Repository configuration (SMTP) | ||||
=============================== | ||||
Edit either repository-local ``.hg/hgrc``, or ``~/.hgrc`` and set | ||||
|
r37 | there all standard email and smtp properties, including SMTP | ||
username, but without SMTP password. For example: | ||||
|
r35 | |||
:: | ||||
[email] | ||||
method = smtp | ||||
from = Joe Doe <Joe.Doe@remote.com> | ||||
[smtp] | ||||
host = smtp.gmail.com | ||||
port = 587 | ||||
username = JoeDoe@gmail.com | ||||
tls = true | ||||
|
r37 | 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. | ||||
|
r35 | |||
Usage | ||||
===== | ||||
|
r36 | Configure the repository as above, then just ``hg pull``, ``hg push``, | ||
etc. You should be asked for the password only once (per every | ||||
|
r35 | username+remote_repository_url combination). | ||
|
r36 | Similarly, for email, configure as above and just ``hg email``. | ||
|
r35 | Again, you will be asked for the password once (per every | ||
username+email_server_name+email_server_port). | ||||
Implementation details | ||||
====================== | ||||
|
r36 | The extension is monkey-patching the mercurial ``passwordmgr`` class | ||
to replace the find_user_password method. Detailed order of operations | ||||
|
r37 | is described in the comments inside `the code`_. | ||
|
r35 | |||
Development | ||||
=========== | ||||
|
r36 | Development is tracked on BitBucket, see | ||
http://bitbucket.org/Mekk/mercurial_keyring/ | ||||
|
r35 | |||
Additional notes | ||||
================ | ||||
Information about this extension is also available | ||||
|
r36 | on Mercurial Wiki: http://mercurial.selenic.com/wiki/KeyringExtension | ||