简体中文 ▾ 主题 ▾ 最新版本 ▾ gitcredentials 上次更新于 2.51.1

名称

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

那么我们将匹配：协议相同，主机也相同。然而，此上下文将不匹配：

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

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

如果 "模式" URL 确实包含路径组件，那么它必须匹配为前缀路径：上下文 https://example.com/bar 将匹配 https://example.com/bar/baz.git 的配置条目，但将不匹配 https://example.com/other/repo.git 或 https://example.com/barry/repo.git 的配置条目（即使它是字符串前缀）。

配置选项

凭据上下文的选项可以在 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 管道命令的输入/输出格式相同（有关详细规范，请参阅 git-credential[1] 中的 INPUT/OUTPUT FORMAT 部分）。

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

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

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

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

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

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

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

如果助手收到任何其他操作，它应该静默忽略该请求。这为将来的操作留有余地（旧助手将简单地忽略新请求）。

GIT

Git[1] 套件的一部分