Mercurial Keyring 扩展
项目描述
Mercurial Keyring 是一个用于在密码数据库（Gnome Keyring、KDE KWallet、OSXKeyChain、Windows Vault 等）中安全保存 HTTP 和 SMTP 身份验证密码的 Mercurial 扩展。
当 mercurial_keyring 激活时，Mercurial 会记住您的密码并在不提示的情况下重用它们（就像您将它们存储在 .hgrc 中一样），但密码存储相对安全。
实际的密码存储是通过 keyring 库实现的，此扩展将其连接到 Mercurial。
1 如何工作
在您第一次从HTTP URL（或通过指定的SMTP服务器发送的第一封电子邮件）进行拉取或推送时，您将需要输入密码，就像裸Mercurial一样。但是，您输入的密码将保存到适当的密码数据库中。在随后的运行中，每当需要密码时，mercurial_keyring都会检查密码数据库中的密码，并使用它而不会打扰您。
如果密码不正确（例如，因为您更改了它或输入错误），mercurial_keyring会再次提示您，并覆盖密码。
您可以使用许多密码（用于各种远程URL）。已保存的密码由用户名和URL前缀的对组成。以下是如何正确配置这些信息的信息。
2 安装
2.1 先决条件
此扩展需要keyring和mercurial_extension_utils才能正常工作。在许多情况下，您在安装mercurial_keyring时，两者都将自动安装，但您可能需要控制此过程。
可以使用以下方法安装keyring库
pip install --user keyring
(或easy_install keyring)，但在某些系统上，使用官方发行版归档更可取。例如，在Debian和Ubuntu上，您可能需要安装python-keyring以及python-keyring-gnome或python-keyring-kwallet软件包
sudo apt-get install python-keyring python-keyring-gnome
(这将避免您提供工作的编译器和各种开发库）。
mercurial_extension_utils模块是一个小巧的Python-only模块，可以通过以下方式安装
pip install --user mercurial_extension_utils
但在某些情况下（Windows……）需要更多的关注。请参阅mercurial_extension_utils文档。
2.2 扩展安装
安装扩展有两种可能的方法：使用PyPi包或使用源克隆。
作为包安装
pip install --user mercurial_keyring
(或sudo pip install mercurial_keyring以系统范围安装)然后在~/.hgrc（或/etc/mercurial/hgrc或Mercurial.ini）中启用它，使用
[extensions] mercurial_keyring =
使用源克隆安装，根据上述说明安装keyring，然后克隆
hg clone https://foss.heptapod.net/mercurial/mercurial_keyring/ hg clone https://foss.heptapod.net/mercurial/mercurial-extension_utils/
并使用扩展模块的完整路径配置Mercurial
[extensions] mercurial_keyring = /path/to/mercurial_keyring/mercurial_keyring.py
3 密码后端配置
通常无需配置即可选择最合适的密码后端（考虑已安装的库、操作系统、活动桌面会话）。尽管如此，如果需要，可以使用keyringrc.cfg文件进行配置。有关更多详细信息，请参阅keyring文档。
4 hgrc 配置（HTTP）
Mercurial Keyring使用标准的Mercurial [auth]配置来检测您在给定远程的登录名和URL前缀。强烈建议您配置这两个参数。
没有用户名，mercurial_keyring无法保存或恢复密码，因此它会禁用自己。
没有url前缀，mercurial_keyring无法工作，但会将密码绑定到仓库URL上。这意味着您将不得不（重新）为从给定远程克隆的每个仓库输入密码（并且这些密码在安全存储中会有很多副本）。
4.1 仓库级别配置
编辑仓库本地的.hg/hgrc文件，并将远程仓库路径和用户名保存到其中，但不要保存密码。例如
[paths] myremote = https://my.server.com/hgrepo/someproject [auth] myremote.prefix = https://my.server.com/hgrepo myremote.username = John
可以使用更简单的带url内嵌名称的表单
[paths] bitbucket = https://John@my.server.com/hgrepo/someproject/
但并不推荐。
请注意，共享相同前缀的所有仓库共享相同的密码。
Mercurial还允许在.hg/hgrc中使用密码（无论是通过«prefix».password提供，还是嵌入到URL中）。如果找到这样的密码，Mercurial Keyring将禁用自己。
4.2 账户级别配置
如果您对远程仓库别名保持一致，您可以在您的~/.hgrc（主目录中的.hgrc）中配置用户名。例如，写入以下内容
[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 = drmartin
只要您使用acme别名来表示类似https://hg.acme.com/repositories/my_beautiful_app的仓库，用户名johnny将被使用，并且将重用相同的密码。同样，任何hg push heptapod都将假定用户名Mekk并共享相同的密码。
使用这种配置，仓库级别的.hg/hgrc只需要包含[paths]。
这种方法的一个额外优点是它也在clone期间工作。
5 hgrc 配置（SMTP）
编辑仓库本地的.hg/hgrc或~/.hgrc，并在其中设置所有标准电子邮件和SMTP属性，包括SMTP用户名，但不包括SMTP密码。例如
[email] method = smtp from = Joe Doe <Joe.Doe@remote.com> [smtp] host = smtp.gmail.com port = 587 username = JoeDoe@gmail.com tls = true
就像HTTP的情况一样，您必须设置用户名，但必须在此处设置密码才能使用扩展，在其他情况下，它将回退到默认行为。
6 用法
6.1 保存和恢复密码
按照上述配置设置仓库后，只需执行hg pull、hg push等。您只需询问一次密码（每个用户名、远程仓库前缀或URL组合一次）。
同样，对于电子邮件，按照上述配置进行配置，然后只需执行hg email。同样，您将只需询问一次密码（每个用户名和电子邮件服务器地址组合一次）。
6.2 检查密码状态（hg keyring_check）
keyring_check命令可以用来检查是否保存了哪些密码。它可以以三种方式使用
没有参数，它打印有关当前仓库定义的所有HTTP路径的相关信息（从hg paths解析为HTTP URL的所有内容）
hg keyring_check
给定别名作为参数，它打印有关此别名的信息
hg keyring_check work
最后，任何路径都可以进行检查
hg keyring_check https://foss.heptapod.net/mercurial/mercurial_keyring
6.3 删除已保存的密码（《hg keyring_clear》）
keyring_clear命令删除与给定路径相关的已保存密码。它可以以两种方式使用
给定别名作为参数，它删除此别名使用的密码
hg keyring_clear work
给定完整路径，它删除与此路径相关的密码
hg keyring_clear https://foss.heptapod.net/mercurial/mercurial_keyring
6.4 使用GUI工具管理密码
许多密码后端提供用于密码管理的GUI工具，例如，Gnome Keyring密码可以使用seahorse进行管理，而KDE Wallet可以使用kwalletmanager。这些GUI工具可以用来查看、编辑或删除已保存的密码。
遗憾的是，在我撰写本文时，keyring 库不允许配置保存密码的确切位置和方式，而且位置并不总是直观。例如，在 KDE 钱包中，使用 mercurial_keyring 保存的所有密码都会显示在名为 Python 的文件夹中。
7 实现细节
该扩展通过 monkey-patching mercurial 的 passwordmgr 类来替换 find_user_password 方法。详细的操作顺序在 代码 内部的注释中描述。
8 常见问题
人们在使用 mercurial_keyring 时遇到的大部分问题实际上都是 keyring 库及其后端的问题。具体来说，这些问题可以表现为
提到类似 没有可用的推荐后端。请安装 keyrings.alt 软件包...（或类似）的句子（或类似），
如 keyring: keyring 后端似乎不工作... 这样的警告
每次操作都会提示密码（= 密码没有保存）。
这些几乎总是意味着给定的桌面类型的 自然 keyring 后端不工作，或者根本不存在。例如，一些必要的运行时组件可能已经关闭（比如，你使用 Linux，但 neither Gnome Keyring，nor KDE 钱包都没有运行）。或者适当的后端没有安装，因为在安装 keyring 库时无法构建（可能是因为在 keyring 安装时缺少某些必需的库，或者可能是因为系统上没有编译器）。
为了诊断这类问题，请尝试使用 keyring 工具，如 keyring 文档页面所述，例如通过
keyring --list-backends keyring -b keyrings.alt.Gnome.Keyring set testsvc testuser keyring -b keyrings.alt.Gnome.Keyring get testsvc testuser
（当然使用适当的后端）。如果你找不到 keyring 命令，请尝试使用 python -m keyring 代替
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
如果适当的后端缺失（未列出），或不工作（第二或第三条命令失败），则你的 keyring 已损坏。请尝试在 keyring 文档、该项目的邮件列表或问题跟踪器中查找更多指针。通常，你需要安装某些缺失的工具或库，然后重新安装 keyring。
如果 keyring 命令工作正常，但使用 mercurial_keyring 的 mercurial 不工作，请尝试强制使用合适的后端（通过 keyringrc.cfg 配置文件，见上文）。如果这仍然不起作用，mercurial_keyring 可能存在一个bug。
使 keyring 正常工作的最简单方法通常是使用打包的二进制版本（例如 Ubuntu 的 python-keyring 软件包，或者某些系统上 TortoiseHG 打包的 keyring）。如果你使用 pip 安装了 keyring 并且它不工作，你可以考虑通过 pip uninstall keyring 来卸载它，并寻找二进制软件包。
9 历史记录
参见 HISTORY.rst。
10 仓库、错误报告、增强建议
开发在 HeptaPod 上进行跟踪，见 https://foss.heptapod.net/mercurial/mercurial_keyring/
使用那里的 issue tracker 进行错误报告和增强建议。
感谢 Octobus 和 Clever Cloud 为此服务提供托管。
11 附加说明
有关此扩展的信息也可在 Mercurial Wiki 上找到：https://www.mercurial-scm.org/wiki/KeyringExtension
还可以查看我编写的其他 Mercurial 扩展：http://code.mekk.waw.pl/mercurial.html。
