English ▾ 主题 ▾ 最新版本 ▾ gitcredentials 上次更新于 2.49.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 中）

社区维护了一个全面的 Git 凭据助手列表，网址为 https://git-scm.cn/doc/credential-helpers。

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-" 将被添加到辅助字符串的前面，结果将成为命令。

然后，生成的命令会附加一个 "operation" 参数（详见下文），结果将由 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 启用它。

当辅助程序执行时，它的命令行会附加一个 "operation" 参数，该参数是以下之一：

get

如果存在匹配的凭据，则返回它。

store

如果适用于辅助程序，则存储凭据。

erase

从辅助程序的存储中删除任何匹配的凭据。

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

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

虽然可以覆盖所有属性，但行为良好的辅助程序应避免这样做，除了用户名和密码之外的任何属性。

如果辅助程序输出一个值为 true 或 1 的 quit 属性，则不会查询其他辅助程序，也不会提示用户（如果没有提供凭据，则操作将失败）。

同样，一旦提供了用户名和密码，就不会再查询其他辅助程序。

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

如果辅助程序无法执行请求的操作或需要通知用户潜在的问题，则可以写入 stderr。

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

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

GIT

属于 git[1] 套件的一部分

scroll-to-top