pass-git-helper

pass-git-helper 是一个 git 凭证助手实现，允许使用 pass 作为基于 HTTPS 的 git 仓库的凭证后端。当 git 尝试与基于 HTTPS 的上游交互并需要凭证时，此助手将被调用以从用户的密码存储中查找凭证。与强制使用特定的密码存储布局不同，该工具使用一个配置文件来明确定义主机和密码存储条目之间的映射，从而给予用户完全的灵活性来组织或重用现有的密码数据库用于 git 认证。pass-git-helper 将使用这些映射根据请求 URL 在用户的密码存储中找到正确的条目，然后将该条目中的凭证提供给 git。

前提条件

建议将 GPG 配置为使用图形化的密码输入程序。这样，当通过 GUI 程序（如 IDE）调用 git 时，你也可以使用此助手。配置示例请参考 ArchWiki。如果你确实想在终端中使用密码输入（通过 pinentry-curses），请确保正确配置环境变量 GPG_TTY，最可能的做法是在你的 shell 初始化文件中添加以下行：

GPG_TTY=$(tty)
export GPG_TTY

如果你通过 SSH 进行远程工作时使用此设置，也可以考虑使用 GPG 代理转发。

安装

官方包

如果可能，请使用适用于你的 Linux 发行版或操作系统的可用包，例如下面链接的包。

从源码安装

sudo pip install .

这可能会在系统包管理器不知情的情况下安装 Python 包。如果所有包的前提条件都已满足，你也可以将脚本文件复制到系统中以避免此问题：

sudo cp passgithelper.py /usr/local/bin/pass-git-helper

另一个选择是在隔离的 virtualenv 中安装脚本：

virtualenv /your/env
/your/env/pip install .

使用方法

配置 git 使用 pass-git-helper

要指示 git 使用该助手，将 git 的 credential.helper 配置选项设置为 /full/path/to/pass-git-helper。如果你不想包含完整路径，可以使用 shell 片段作为解决方案，即选项值必须为 !pass-git-helper $@。可以使用 CLI 设置该选项：

git config credential.helper '!pass-git-helper $@'

这将在 ~/.gitconfig 中产生以下内容：

[credential]
    helper = !pass-git-helper $@

如果你在多台机器上共享 ~/.gitconfig，而 pass-git-helper 并非在所有机器上都可用，以下版本在 pass git helper 缺失时不会报错：

[credential]
    helper = !type pass-git-helper >/dev/null && pass-git-helper $@

pass-git-helper 可以与其他助手结合使用。例如，以下配置首先尝试 git 内置的 cache 助手进行内存中的密码访问，如果缓存未命中则回退到 pass-git-helper：

[credential]
    helper = cache
    helper = !type pass-git-helper >/dev/null && pass-git-helper$@

定义映射

创建文件 ~/.config/pass-git-helper/git-pass-mapping.ini。此文件使用 ini 语法来指定主机到密码存储数据库条目的映射。配置文件中的第一个匹配映射用于选择密码存储数据库中的条目。这个搜索过程基于配置文件中的定义顺序。

节标题定义了与 git 仓库 URL 的主机部分匹配的模式。匹配支持通配符（使用 Python fnmatch 模块）。

每个节需要包含一个 target 条目，指向密码存储中包含要使用的密码（和可选的用户名）的条目。

示例：

[github.com*]
target=dev/github

[*.fooo-bar.*]
target=dev/fooo-bar

如果你想不仅基于主机，还基于主机上的路径来匹配条目，请在你的 git 配置中将 credential.useHttpPath 设置为 true，例如通过：

git config credential.useHttpPath true

之后，可以在映射中针对 host.com/path/to/repo 匹配条目。这意味着为了对某个特定的 Github 项目使用特定账户，你可以使用以下映射模式：

[github.com/username/project*]
target=dev/github

请注意，当在映射中包含路径时，映射表达式需要匹配整个路径。因此，如果你想对所有 Github 项目使用相同的账户，你需要确保通配符覆盖 URL 的路径，如下所示：

[github.com*]
target=dev/github

主机可以用作变量来指向 pass 条目。这对于通配符匹配特别有用：

[*]
target=git-logins/${host}

上述配置指令将导致任何未在 ini 文件中匹配到先前节的主机都在密码存储的 git-logins 目录下查找。

除了 ${host}，还可以使用变量 ${username} 和 ${protocol} 进行替换。

DEFAULT 节

适用于映射文件所有条目的默认设置可以在配置文件的一个特殊节 [DEFAULT] 中指定。在此节中配置的所有内容将自动适用于文件中的所有后续条目，但也可以在那里被覆盖。

根据工作目录使用不同的映射

使用 git >= 2.13 中可用的 includeIf 指令，可以通过使用条件 MAPPING-FILE 调用 pass-git-helper 来基于当前工作目录执行匹配。要实现这一点，编辑你的 .gitconfig，例如像这样：

[includeIf "gitdir:~/src/user1/"]
    path=~/.config/git/gitconfig_user1
[includeIf "gitdir:~/src/user2/"]
    path=~/.config/git/gitconfig_user2

使用以下 gitconfig_user1（和相应的 gitconfig_user2）内容，mapping_user1.ini（可能包含一个指向例如 github.com/user1 的 target 条目）将始终在 ~/src/user1 中被调用：

[user]
    name = user1
[credential]
    helper=/full/path/to/pass-git-helper -m /full/path/to/mapping_user1.ini

另请参阅 .gitconfig 的官方文档。

按映射切换密码存储

要为特定条目选择不同的密码存储，可以设置 password_store_dir 配置键。如果设置为非空值，pass 会通过在调用时定义 PASSWORD_STORE_DIR 环境变量来指向不同的数据目录。如果 password_store_dir 值以波浪号（~）开头，它将被替换为用户的HOME目录（即 HOME 环境变量的值，在 Windows 上则是 USERPROFILE 环境变量的值，详见 os.path.expanduser()）。

以下配置演示了这些做法：

[github.com/mycompany]
password_store_dir=~/.work-passwords

密码存储布局和数据提取

密码

与pass的常规用法一样，此助手假定密码包含在密码存储条目的第一行。虽然不常见，但可以通过在条目的 skip_password 字段中指定要省略的字符数来去除第一行数据的前缀（如 password:），也可以在 [DEFAULT] 部分应用于所有条目：

[DEFAULT]
# "password: "的长度
skip_password=10

[somedomain]
# 由于某些原因，此条目没有密码前缀
skip_password=0
target=special/noprefix

用户名

pass-git-helper 还可以提供认证服务器所需的用户名。与密码不同，密码条目中存储用户名信息没有明确的约定。因此，实现了多种提取用户名的策略，可以在 [DEFAULT] 部分全局选择整个密码存储的策略，或使用 username_extractor 键为某些条目单独选择：

[DEFAULT]
username_extractor=regex_search
regex_username=^user: (.*)$

[differingdomain.com]
# 这里使用固定行而不是正则表达式搜索
username_extractor=specific_line
line_username=1

可以配置以下策略：

"specific_line" 策略（默认）

通过行号提取数据。可选择在返回行内容之前去除固定长度的前缀。

配置：

line_username：包含用户名的行号，从0开始。默认：1（第二行）
skip_username：行首要跳过的字符数，例如跳过 user: 前缀。类似于 skip_password。默认：0。

"regex_search" 策略

搜索匹配提供的正则表达式的第一行，并返回该行中被正则表达式捕获组捕获的内容。

内部使用Python正则表达式，你可以使用所有提供的语法功能。

配置：

regex_username：要应用的正则表达式。必须包含一个单一的捕获组以指示要提取的数据。如果你的正则表达式需要括号来匹配非用户名的部分，可以使用非捕获括号（即 (?:...)）。默认：^username: +(.*)$。

"entry_name" 策略

返回密码存储条目的最后一个路径片段作为用户名。例如，如果常规的pass调用是 pass show dev/github.com/languitar，返回的用户名将是 languitar。

没有配置选项。

文件编码

默认情况下，假定密码存储条目使用UTF-8编码。如果所有或部分条目使用不同的编码，请使用 encoding 键（例如，在 DEFAULT 部分）指定所使用的编码。

命令行选项

可以给脚本传递 -l 选项以在标准错误输出上产生日志输出。这可能有助于理解如何应用映射。

可以指定 -m MAPPING_FILE 以使用替代的映射文件位置。

跳过处理

在某些自动化上下文中，可能需要防止GPG询问密码短语（通过代理）。为了实现这一点，你可以通过定义环境变量 PASS_GIT_HELPER_SKIP 并赋予任何内容（或不赋值）来禁用此助手的完整处理。在这种情况下，pass-git-helper 将立即返回，向git表明没有找到合适的凭据。

许可证

本库是自由软件；你可以根据自由软件基金会发布的GNU Lesser General Public License的条款重新分发和/或修改它；可以选择使用许可证的第3版或任何更新的版本。本作品的分发是希望它能有用，但不提供任何保证；甚至不保证适销性或特定用途的适用性。详情请参阅GNU Lesser General Public License。