Git
英语 ▾ 主题 ▾ 最新版本 ▾ git-credential 最后更新于 2.46.0

名称

git-credential - 检索和存储用户凭据

概要

'git credential' (fill|approve|reject|capability)

描述

Git 具有一个内部接口，用于从特定于系统的帮助程序中存储和检索凭据，以及提示用户输入用户名和密码。git-credential 命令将此接口公开给可能希望以与 Git 相同的方式检索、存储或提示凭据的脚本。此可脚本化接口的设计模拟了内部 C API；有关这些概念的更多背景信息，请参见 credential.h。

git-credential 在命令行上接受一个“操作”选项（fill、approve 或 reject 中的一个）并在标准输入上读取凭据描述（参见 输入/输出格式）。

如果操作为 fill，git-credential 将尝试通过读取配置文件、联系任何已配置的凭据助手或提示用户，在描述中添加“用户名”和“密码”属性。然后，凭据描述的用户名和密码属性将与已提供的属性一起打印到标准输出。

如果操作为 approve，git-credential 将将描述发送到任何已配置的凭据助手，这些助手可能会将凭据存储以供将来使用。

如果操作为 reject，git-credential 将将描述发送到任何已配置的凭据助手，这些助手可能会擦除与描述匹配的任何存储的凭据。

如果操作为 capability，git-credential 将向标准输出宣布其支持的任何功能。

如果操作为 approve 或 reject，则不应发出任何输出。

GIT 凭据的典型用法

使用 git-credential 的应用程序通常会按照以下步骤使用 git credential

  1. 根据上下文生成凭据描述。

    例如，如果我们要获取 https://example.com/foo.git 的密码，我们可能会生成以下凭据描述（不要忘记末尾的空行；它告诉 git credential 应用程序已完成提供其拥有的所有信息）

    protocol=https
host=example.com
path=foo.git

  2. 要求 git-credential 为此描述提供用户名和密码。这是通过运行 git credential fill 来完成的，将步骤 (1) 中的描述提供给它的标准输入。完整的凭据描述（包括凭据本身，即登录名和密码）将在标准输出上生成，如下所示

    protocol=https
host=example.com
username=bob
password=secr3t

    在大多数情况下，这意味着输入中给出的属性将在输出中重复，但 Git 也可以修改凭据描述，例如，当协议为 HTTP(s) 且 credential.useHttpPath 为 false 时，删除 path 属性。

    如果 git credential 知道密码，则此步骤可能不涉及用户实际键入此密码（用户可能键入密码以解锁密钥链，或者如果密钥链已解锁，则没有用户交互）然后它返回 password=secr3t。

  3. 使用凭据（例如，使用步骤 (2) 中的用户名和密码访问 URL），并查看它是否被接受。

  4. 报告密码的成功或失败。如果凭据允许操作成功完成，则可以使用“批准”操作对其进行标记，以告诉 git credential 在其下次调用中重新使用它。如果在操作期间拒绝了凭据，请使用“拒绝”操作，以便 git credential 在其下次调用中要求新的密码。在这两种情况下，都应将步骤 (2) 中获得的凭据描述（其中还包含步骤 (1) 中提供的字段）提供给 git credential。

输入/输出格式

git credential 在其标准输入/输出中读取和/或写入（取决于使用的操作）凭据信息。此信息可以对应于 git credential 将为其获取登录信息（例如主机、协议、路径）的密钥，也可以对应于要获取的实际凭据数据（用户名/密码）。

凭据被分成一组命名属性，每行一个属性。每个属性由一个键值对指定，用 =（等号）分隔，后跟一个换行符。

键可以包含除 =、换行符或 NUL 之外的任何字节。值可以包含除换行符或 NUL 之外的任何字节。一行（包括尾随换行符）不得超过 65535 个字节，以便实现能够高效地进行解析。

键以 C 样式数组括号 [] 结尾的属性可以具有多个值。多值属性的每个实例形成一个有序的值列表 - 重复属性的顺序定义了值的顺序。空多值属性（key[]=\n）的作用是清除所有以前的条目并重置列表。

在所有情况下，所有字节都按原样处理（即，没有引用，并且无法传输包含换行符或 NUL 的值）。属性列表以空行或文件结尾终止。

Git 理解以下属性

protocol

将使用凭据的协议（例如，https）。

host

网络凭据的远程主机名。这包括端口号（如果指定了端口号）（例如，“example.com:8088”）。

path

将使用凭据的路径。例如，对于访问远程 https 存储库，这将是服务器上的存储库路径。

username

凭据的用户名，如果我们已经有一个用户名（例如，来自 URL、配置、用户或之前运行的助手）。

password

凭据的密码，如果我们要求存储它。

password_expiry_utc

生成的密码（如 OAuth 访问令牌）可能具有过期日期。从助手读取凭据时，git credential fill 会忽略过期的密码。用 Unix 时间 UTC 表示，自 1970 年以来的秒数。

oauth_refresh_token

OAuth 刷新令牌可能与 OAuth 访问令牌密码一起使用。助手必须像密码属性一样将此属性视为机密信息。Git 本身对此属性没有特殊行为。

url

当 git credential 读取此特殊属性时，该值将被解析为 URL 并像读取其组成部分一样进行处理（例如，url=https://example.com 的行为就像提供了 protocol=https 和 host=example.com 一样）。这可以帮助调用者避免自己解析 URL。

请注意，指定协议是强制性的，如果 URL 未指定主机名（例如，“cert:///path/to/file”），则凭据将包含一个主机名属性，其值为一个空字符串。

URL 中缺少的组件（例如，上面的示例中没有用户名）将保持未设置状态。

authtype

这表示应使用所讨论的身份验证方案。HTTP 和 HTTPS 的常用值包括 basic、bearer 和 digest，尽管后者不安全，不应使用。如果使用 credential，则可以将其设置为适用于所讨论协议的任意字符串（通常为 HTTP）。

除非在输入中提供了相应的功能（见下文），否则不应发送此值。

credential

预编码的凭据，适用于所讨论的协议（通常为 HTTP）。如果发送此键，authtype 是强制性的，并且不使用 username 和 password。对于 HTTP，Git 将 authtype 值和此值与单个空格连接起来，以确定 Authorization 标头。

除非在输入中提供了相应的功能（见下文），否则不应发送此值。

ephemeral

此布尔值表示，如果为 true，则凭据助手不应保存 credential 字段中的值，因为它的用处是有限的。例如，HTTP Digest credential 值是使用 nonce 计算的，重用它不会导致成功身份验证。这也适用于使用时间较短的凭据的情况（例如，24 小时）。默认值为 false。

凭据助手仍将使用 store 或 erase 被调用，以便它可以确定操作是否成功。

除非在输入中提供了相应的功能（见下文），否则不应发送此值。

state[]

此值提供一个不透明状态，如果再次调用此帮助程序，该状态将传递回此帮助程序。每个不同的凭据帮助程序都可能只指定此状态一次。该值应包含凭据帮助程序独有的前缀，并应忽略与该前缀不匹配的值。

除非在输入中提供了相应的功能（见下文），否则不应发送此值。

continue

这是一个布尔值，如果启用，则表示此身份验证是多阶段身份验证步骤的非最终部分。这在 NTLM 和 Kerberos 等协议中很常见，其中需要两轮客户端身份验证，设置此标志允许凭据帮助程序实现多阶段身份验证步骤。仅在需要进一步阶段时才应发送此标志；也就是说，如果预计会有另一轮身份验证。

除非输入提供了相应的支持功能（见下文），否则不应发送此值。此属性是**单向的**，从凭据帮助程序传递信息给 Git（或调用git credential的其他程序）。

wwwauth[]

当 Git 接收到包含一个或多个WWW-Authenticate身份验证标头的 HTTP 响应时，Git 会将这些标头传递给凭据帮助程序。

每个WWW-Authenticate标头值都作为多值属性wwwauth[]传递，其中属性的顺序与其在 HTTP 响应中的出现顺序相同。此属性是**单向的**，从 Git 传递附加信息给凭据帮助程序。

capability[]

这表示 Git 或帮助程序（视情况而定）支持该功能。这可用于在协议中提供更好、更具体的數據。capability[]指令必须在任何依赖于它的值之前，这些指令**应该**是协议中宣布的第一个项目。

目前有两种支持的功能。第一个是authtype，它表示authtype、credential和ephemeral值是可理解的。第二个是state，它表示state[]和continue值是可理解的。

仅因为支持该功能而并非必须使用附加功能，但如果没有该功能，则不应提供附加功能。

无法识别的属性和功能将被静默丢弃。

功能输入/输出格式

对于git credential capability，格式略有不同。首先，会宣布version 0来指示协议的当前版本，然后会宣布每个功能，方法是使用类似于capability authtype的行。凭据帮助程序也可以实现这种格式，同样使用capability参数。将来可能会添加更多行；调用者应该忽略他们不理解的行。

由于这是凭据帮助程序协议的新部分，因此旧版本的 Git 以及一些凭据帮助程序可能不支持它。如果收到非零退出状态，或者如果第一行没有以单词version和空格开头，则调用者应该假设不支持任何功能。

这种格式的意图是用一种明确的方式将它与凭据输出区分开来。可以使用非常简单的凭据帮助程序（例如内联 shell 脚本），这些帮助程序始终产生相同的输出。使用不同的格式允许用户继续使用这种语法，而不必担心正确地实现功能广告或意外地混淆查询功能的调用者。

GIT

是 git[1] 套件的一部分

scroll-to-top