简体中文 ▾ 主题 ▾ 最新版本 ▾ gitcredentials 最后更新于 2.50.0

名称

gitcredentials - 向 Git 提供用户名和密码

概要

git config credential.https://example.com.username myusername
git config credential.helper "$helper $options"

描述

Git 有时需要用户凭证来执行操作；例如，它可能需要请求用户名和密码以通过 HTTP 访问远程仓库。某些远程仓库接受个人访问令牌或 OAuth 访问令牌作为密码。本手册描述了 Git 请求这些凭证的机制，以及一些避免重复输入这些凭证的功能。

请求凭证

在未定义任何凭证助手的情况下，Git 将尝试以下策略向用户请求用户名和密码：

  1. 如果设置了 GIT_ASKPASS 环境变量，则调用该变量指定的程序。命令行上会向该程序提供合适的提示，用户的输入将从其标准输出中读取。

  2. 否则，如果设置了 core.askPass 配置变量，则其值将按上述方式使用。

  3. 否则，如果设置了 SSH_ASKPASS 环境变量，则其值将按上述方式使用。

  4. 否则，将提示用户在终端上输入。

避免重复

重复输入相同的凭证可能会很麻烦。Git 提供了两种方法来减少这种困扰：

  1. 为给定的身份验证上下文静态配置用户名。

  2. 凭证助手，用于缓存或存储密码，或与系统密码钱包或钥匙串交互。

第一种方法很简单，并且在你没有可用于密码的安全存储时适用。通常通过将以下内容添加到你的配置中来配置它：

[credential "https://example.com"]
	username = me

另一方面，凭证助手是 Git 可以从中请求用户名和密码的外部程序；它们通常与操作系统或其他程序提供的安全存储接口。此外，凭证生成助手可能通过某些 API 为特定服务器生成凭证。

要使用助手，你必须首先选择一个（有关列表，请参阅下文）。

你也可能安装了第三方助手；在 git help -a 的输出中搜索 credential-*，并查阅各个助手的文档。一旦你选择了助手，你可以通过将其名称放入 credential.helper 变量来告诉 Git 使用它。

  1. 寻找一个助手。

    $ git help -a | grep credential-
credential-foo

  2. 阅读其描述。

    $ git help credential-foo

  3. 告诉 Git 使用它。

    $ git config --global credential.helper foo

可用助手

Git 目前包含以下助手：

cache

在内存中短期缓存凭证。有关详细信息，请参阅 git-credential-cache[1]。

store

将凭证无限期存储在磁盘上。有关详细信息，请参阅 git-credential-store[1]。

包含安全持久存储的流行助手包括：

  • git-credential-libsecret (Linux)

  • git-credential-osxkeychain (macOS)

  • git-credential-wincred (Windows)

  • Git Credential Manager (跨平台，包含在 Git for Windows 中)

社区在 https://git-scm.cn/doc/credential-helpers 维护着一份全面的 Git 凭证助手列表。

OAuth

输入密码或个人访问令牌的另一种方法是使用 OAuth 凭证助手。初始身份验证会打开一个浏览器窗口到主机。后续身份验证在后台进行。许多流行的 Git 主机支持 OAuth。

支持 OAuth 的流行助手包括：

凭证上下文

Git 认为每个凭证都有一个由 URL 定义的上下文。此上下文用于查找特定于上下文的配置，并传递给任何助手，助手可能将其用作安全存储的索引。

例如，假设我们正在访问 https://example.com/foo.git。当 Git 在配置文件中查看某个部分是否与此上下文匹配时，如果上下文是配置文件中模式的更具体子集，则它们被认为是匹配的。例如，如果你的配置文件中有以下内容：

[credential "https://example.com"]
	username = foo

那么我们将匹配：协议相同，主机相同，并且“模式”URL 完全不关心路径组件。但是，此上下文将不匹配：

[credential "https://linuxkernel.org.cn"]
	username = foo

因为主机名不同。它也不会匹配 foo.example.com；Git 完全比较主机名，不考虑两个主机是否属于同一域。同样，http://example.com 的配置条目也不会匹配：Git 完全比较协议。但是，你可以在域名中使用通配符和其他模式匹配技术，就像 http.<URL>.* 选项一样。

如果“模式”URL 确实包含路径组件，那么这也必须精确匹配：上下文 https://example.com/bar/baz.git 将匹配 https://example.com/bar/baz.git 的配置条目（除了匹配 https://example.com 的配置条目），但不会匹配 https://example.com/bar 的配置条目。

配置选项

凭证上下文的选项可以在 credential.*（适用于所有凭证）或 credential.<URL>.* 中配置，其中 <URL> 如上所述匹配上下文。

以下选项在任一位置都可用：

helper

外部凭证助手的名称以及任何相关选项。如果助手名称不是绝对路径，则会预置字符串 git credential-。生成的字符串由 shell 执行（因此，例如，将其设置为 foo --option=bar 将通过 shell 执行 git credential-foo --option=bar）。有关其使用示例，请参阅特定助手的文档。

如果 credential.helper 配置变量有多个实例，则每个助手将依次尝试，并可能提供用户名、密码或不提供任何内容。一旦 Git 获得了用户名和未过期的密码，将不再尝试其他助手。

如果 credential.helper 配置为空字符串，则这会将助手列表重置为空（因此，你可以通过配置空字符串助手，然后是所需的助手集，来覆盖由低优先级配置文件设置的助手）。

username

默认用户名，如果 URL 中未提供。

useHttpPath

默认情况下，Git 不认为 http URL 的“路径”组件值得通过外部助手进行匹配。这意味着为 https://example.com/foo.git 存储的凭证也将用于 https://example.com/bar.git。如果你确实想区分这些情况，请将此选项设置为 true。

自定义助手

你可以编写自己的自定义助手，以与你存储凭证的任何系统进行接口。

凭证助手是 Git 执行的程序，用于从长期存储中获取或保存凭证（其中“长期”只是比单个 Git 进程更长；例如，凭证可以保存在内存中几分钟，或无限期地保存在磁盘上）。

每个助手都由配置变量 credential.helper（以及其他，参见 git-config[1]）中的单个字符串指定。Git 根据以下规则将该字符串转换为要执行的命令：

  1. 如果助手字符串以“!”开头，则它被视为 shell 片段，并且“!”之后的所有内容都成为命令。

  2. 否则，如果助手字符串以绝对路径开头，则原样助手字符串成为命令。

  3. 否则，将字符串“git credential-”预置到助手字符串，结果成为命令。

然后，生成的命令会附加一个“操作”参数（有关详细信息，请参阅下文），并由 shell 执行结果。

以下是一些示例规范：

# run "git credential-foo"
[credential]
	helper = foo

# same as above, but pass an argument to the helper
[credential]
	helper = "foo --bar=baz"

# the arguments are parsed by the shell, so use shell
# quoting if necessary
[credential]
	helper = "foo --bar='whitespace arg'"

# store helper (discouraged) with custom location for the db file;
# use `--file ~/.git-secret.txt`, rather than `--file=~/.git-secret.txt`,
# to allow the shell to expand tilde to the home directory.
[credential]
	helper = "store --file ~/.git-secret.txt"

# you can also use an absolute path, which will not use the git wrapper
[credential]
	helper = "/path/to/my/helper --with-arguments"

# or you can specify your own shell snippet
[credential "https://example.com"]
	username = your_user
	helper = "!f() { test \"$1\" = get && echo \"password=$(cat $HOME/.secret)\"; }; f"

一般来说，上述规则（3）对用户来说最简单。凭证助手的作者应努力通过将其程序命名为“git-credential-$NAME”，并在安装期间将其放入 $PATH 或 $GIT_EXEC_PATH 来帮助其用户，这将允许用户使用 git config credential.helper $NAME 启用它。

当助手执行时，其命令行将附加一个“操作”参数，该参数是以下之一：

get

返回匹配的凭证（如果存在）。

store

存储凭证，如果适用于助手。

erase

从助手的存储中删除匹配的凭证（如果存在）。

凭证的详细信息将通过助手的 stdin 流提供。确切的格式与 git credential 底层命令的输入/输出格式相同（有关详细规范，请参阅 git-credential[1] 中的 INPUT/OUTPUT FORMAT 部分）。

对于 get 操作，助手应以相同的格式在 stdout 上生成属性列表（有关常见属性，请参阅 git-credential[1]）。助手可以自由地生成子集，甚至在没有有用的值时完全不生成任何值。任何提供的属性都将覆盖 Git 凭证子系统已知的属性。无法识别的属性将被静默丢弃。

虽然可以覆盖所有属性，但表现良好的助手应避免对用户名和密码以外的任何属性执行此操作。

如果助手输出一个值为 true 或 1 的 quit 属性，则不会再咨询其他助手，也不会提示用户（如果未提供凭证，则操作将失败）。

同样，一旦提供了用户名和密码，将不再咨询其他助手。

对于 store 或 erase 操作，助手的输出将被忽略。

如果助手未能执行请求的操作或需要通知用户潜在问题，它可能会写入 stderr。

如果它不支持请求的操作（例如，只读存储或生成器），它应该静默忽略该请求。

如果助手收到任何其他操作，它应该静默忽略该请求。这为将来添加新操作留下了空间（较旧的助手将只忽略新请求）。

GIT

Git[1] 套件的一部分

scroll-to-top