简体中文 ▾ 主题 ▾ 最新版本 ▾ gitremote-helpers 上次更新于 2.51.0

名称

gitremote-helpers - 与远程存储库交互的辅助程序

概要

git remote-<transport> <repository> [<URL>]

描述

远程辅助程序通常不直接被最终用户使用，但当 Git 需要与 Git 本身不支持的远程存储库交互时，它们会被调用。给定的辅助程序将实现此处记录的功能的一个子集。当 Git 需要与远程辅助程序交互时，它会将该辅助程序作为独立进程启动，将命令发送到该辅助程序的标准输入，并期望从其标准输出获取结果。由于远程辅助程序作为 Git 的独立进程运行，因此无需重新链接 Git 来添加新的辅助程序，也无需将辅助程序与 Git 的实现链接。

每个辅助程序都必须支持“capabilities”命令，Git 使用此命令来确定辅助程序还将接受哪些其他命令。这些其他命令可用于发现和更新远程引用、在对象数据库和远程存储库之间传输对象以及更新本地对象存储。

Git 提供了“curl”系列的远程辅助程序，它们处理各种传输协议，例如 git-remote-http、git-remote-https、git-remote-ftp 和 git-remote-ftps。它们实现了 fetch、option 和 push 的功能。

调用

远程辅助程序通过一个或（可选）两个参数调用。第一个参数指定 Git 中的远程存储库，它是已配置的远程名称或 URL。第二个参数指定一个 URL，通常形式为 <transport>://<address>，但也可以是任何任意字符串。 GIT_DIR 环境变量为远程辅助程序设置，可用于确定存储额外数据的位置或从哪个目录调用辅助 Git 命令。

当 Git 遇到 <transport>://<address> 形式的 URL 时，其中 <transport> 是 Git 无法原生处理的协议，它会自动调用 git remote-<transport>，并将完整 URL 作为第二个参数。如果直接在命令行中遇到此类 URL，第一个参数与第二个参数相同；如果是在已配置的远程中遇到，第一个参数是该远程的名称。

<transport>::<address> 形式的 URL 会明确指示 Git 调用 git remote-<transport>，并将 <address> 作为第二个参数。如果直接在命令行中遇到此类 URL，第一个参数是 <address>；如果是在已配置的远程中遇到，第一个参数是该远程的名称。

此外，当已配置的远程的 remote.<name>.vcs 设置为 <transport> 时，Git 会显式调用 git remote-<transport>，并将 <name> 作为第一个参数。如果设置了，第二个参数是 remote.<name>.url；否则，第二个参数将被省略。

输入格式

Git 将命令列表发送到标准输入，每行一个命令。第一个命令始终是 capabilities 命令，响应此命令时，远程辅助程序必须打印其支持的功能列表（如下所述），后跟一个空行。对 capabilities 命令的响应决定了 Git 在命令流的其余部分中使用哪些命令。

命令流以空行结束。在某些情况下（在相关命令的文档中指示），此空行后会跟其他协议（例如 pack 协议）的有效负载，而在其他情况下，它表示输入结束。

功能

每个远程辅助程序都应只支持命令的一个子集。辅助程序支持的操作通过响应 capabilities 命令（参见下文的 COMMANDS）向 Git 声明。

下面列出了所有已定义的功能，并为每种功能列出了辅助程序必须提供的命令。

推送功能

connect

可以尝试连接到 git receive-pack（用于推送）、git upload-pack 等，以便使用 Git 的原生 packfile 协议进行通信。这需要双向全双工连接。

支持的命令：connect。

stateless-connect

实验性功能；仅供内部使用。可以尝试连接到远程服务器，以便使用 Git 的 wire-protocol 版本 2 进行通信。有关 stateless-connect 命令的更多信息，请参阅文档。

支持的命令：stateless-connect。

push

可以发现远程引用并将本地提交及其依赖的历史推送到新的或现有的远程引用。

支持的命令：list for-push、push。

export

可以发现远程引用并将来自 fast-import 流的指定对象推送到远程引用。

支持的命令：list for-push、export。

如果辅助程序声明了 connect，Git 将在可能的情况下使用它，并在连接时（参见 COMMANDS 下的 connect 命令）如果辅助程序请求则回退到其他功能。在 push 和 export 之间选择时，Git 优先使用 push。其他前端可能有不同的偏好顺序。

no-private-update

在使用 refspec 功能时，git 通常会在成功推送后更新私有引用。当远程辅助程序声明 no-private-update 功能时，此更新将被禁用。

获取功能

connect

可以尝试连接到 git upload-pack（用于获取）、git receive-pack 等，以便使用 Git 的原生 packfile 协议进行通信。这需要双向全双工连接。

支持的命令：connect。

stateless-connect

实验性功能；仅供内部使用。可以尝试连接到远程服务器，以便使用 Git 的 wire-protocol 版本 2 进行通信。有关 stateless-connect 命令的更多信息，请参阅文档。

支持的命令：stateless-connect。

fetch

可以发现远程引用并将可从它们到达的对象传输到本地对象存储。

支持的命令：list、fetch。

import

可以发现远程引用并将可从它们到达的对象以 fast-import 格式的流输出。

支持的命令：list、import。

check-connectivity

可以保证在请求克隆时，接收到的 pack 文件是独立的且已连接。

get

可以使用 get 命令从给定 URI 下载文件。

如果辅助程序声明了 connect，Git 将在可能的情况下使用它，并在连接时（参见 COMMANDS 下的 connect 命令）如果辅助程序请求则回退到其他功能。在 fetch 和 import 之间选择时，Git 优先使用 fetch。其他前端可能有不同的偏好顺序。

杂项功能

option

用于指定如 verbosity（向 stderr 写入多少输出）和 depth（浅克隆情况下需要多少历史记录）等设置，这些设置会影响其他命令的执行方式。

refspec <refspec>

对于实现 import 或 export 功能的远程辅助程序，此功能允许将引用限制在私有命名空间中，而不是直接写入 refs/heads 或 refs/remotes。建议所有提供 import 功能的导入程序使用此功能。对于 export，这是必需的。

声明了 refspec refs/heads/*:refs/svn/origin/branches/* 功能的辅助程序表示，当它被要求 import refs/heads/topic 时，它输出的流将更新 refs/svn/origin/branches/topic 引用。

此功能可以被多次声明。第一个适用的 refspec 具有优先权。使用此功能声明的 refspec 的左侧必须涵盖 list 命令报告的所有引用。如果没有声明 refspec 功能，则隐含 refspec *:*。

在编写去中心化版本控制系统的远程辅助程序时，建议保留存储库的本地副本进行交互，并让私有命名空间引用指向此本地存储库，而 refs/remotes 命名空间用于跟踪远程存储库。

bidi-import

此功能修改了 import 功能。fast-import 命令 cat-blob 和 ls 可供远程辅助程序使用，以检索 fast-import 内存中已存在的 blob 和 tree 的信息。这需要一个从 fast-import 到远程辅助程序的通道。如果它与“import”一起声明，Git 将建立一个从 fast-import 到远程辅助程序 stdin 的管道。因此，Git 和 fast-import 都连接到远程辅助程序的 stdin。由于 Git 可以向远程辅助程序发送多个命令，因此要求使用 bidi-import 的辅助程序在将数据发送到 fast-import 之前缓冲批处理的所有 import 命令。这是为了防止命令和 fast-import 响应在辅助程序的 stdin 上混淆。

export-marks <file>

此功能修改了 export 功能，指示 Git 在完成后将内部 marks 表转储到 <file>。有关详细信息，请参阅 git-fast-export[1] 中的 --export-marks=<file>。

import-marks <file>

此功能修改了 export 功能，指示 Git 在处理任何输入之前加载 <file> 中指定的 marks。有关详细信息，请参阅 git-fast-export[1] 中的 --import-marks=<file>。

signed-tags

此功能修改了 export 功能，指示 Git 将 --signed-tags=verbatim 传递给 git-fast-export[1]。如果缺少此功能，Git 将使用 --signed-tags=warn-strip。

object-format

这表明辅助程序能够使用显式的哈希算法扩展与远程端进行交互。

命令

命令由调用者通过辅助程序的标准输入发送，每行一个。

capabilities

列出辅助程序的功能，每行一个，以空行结尾。每个功能前面可能有一个 *，这表示 Git 使用远程辅助程序进行理解的版本必须理解这些功能。任何未知的强制功能都是致命错误。

支持此命令是强制性的。

list

列出引用，每行一个，格式为“<value> <name> [<attr> …​]”。值可以是十六进制 sha1 哈希、指向符号引用的“@<dest>”、键值对的“:<keyword> <value>”，或“?”表示辅助程序无法获取引用的值。名称后面是空格分隔的属性列表；未识别的属性将被忽略。列表以空行结束。

有关当前定义的属性列表，请参阅 REF LIST ATTRIBUTES。有关当前定义的关键字列表，请参阅 REF LIST KEYWORDS。

如果辅助程序具有“fetch”或“import”功能，则支持此命令。

list for-push

与 list 类似，但仅当调用者希望生成的引用列表用于准备推送命令时才使用。支持推送和获取的辅助程序可以使用此命令来区分 list 的输出将用于哪个操作，从而可能减少需要执行的工作量。

如果辅助程序具有“push”或“export”功能，则支持此命令。

option <name> <value>

将传输辅助程序选项 <name> 设置为 <value>。输出一行，包含 ok（选项成功设置）、unsupported（选项未识别）或 error <msg>（选项 <name> 受支持但 <value> 对其无效）。选项应在其他命令之前设置，并且可能会影响这些命令的行为。

有关当前定义的选项列表，请参阅 OPTIONS。

如果辅助程序具有“option”功能，则支持此命令。

fetch <sha1> <name>

获取指定的对象，将必要的对象写入数据库。Fetch 命令以批处理方式发送，每行一个，以空行结束。当同一批次中的所有 fetch 命令完成后，输出一个空行。只能通过这种方式获取在 list 命令的输出中用 sha1 报告的对象。

可选地，可以输出一行 lock <file>，指示 $GIT_DIR/objects/pack 下用于在引用被适当地更新之前保持 pack 文件的完整路径。路径必须以 .keep 结尾。这是一种通过仅提供 keep 组件来命名 <pack,idx,keep> 元组的机制。即使其对象在 fetch 完成之前可能未被引用，kept pack 也不会被并发的 repack 删除。fetch 完成时将删除 .keep 文件。

如果请求了 check-connectivity 选项，如果克隆是独立的且已连接，则辅助程序必须输出 connectivity-ok。

如果辅助程序具有“fetch”功能，则支持此命令。

push +<src>:<dst>

将给定的本地 <src> commit 或 branch 推送到由 <dst> 描述的远程 branch。一系列一个或多个 push 命令以空行结束（如果只有一个引用要推送，则单个 push 命令后跟一个空行）。例如，以下将是两个 push 批处理，第一个要求远程辅助程序将本地引用 master 推送到远程引用 master 以及本地 HEAD 推送到远程 branch，第二个要求将引用 foo 推送到引用 bar（由 + 请求强制更新）。

push refs/heads/master:refs/heads/master
push HEAD:refs/heads/branch
\n
push +refs/heads/foo:refs/heads/bar
\n

在批次的最后一个 push 命令之后、批次终止空行之前，可以输入零个或多个协议选项。

推送完成后，输出一行或多行 ok <dst> 或 error <dst> <why>? 以指示每个推送引用的成功或失败。状态报告输出以空行结束。如果 <why> 字段包含 LF，则可以使用 C 风格字符串进行引用。

如果辅助程序具有“push”功能，则支持此命令。

import <name>

生成一个 fast-import 流，该流导入命名引用的当前值。它还可以导入其他必要的引用以高效地构建历史。脚本写入辅助程序特定的私有命名空间。命名引用的值应写入此命名空间中的一个位置，该位置是通过将“refspec”功能的 refspec 应用于引用名称派生而来的。

尤其适用于与外部版本控制系统进行互操作。

与 push 类似，一系列一个或多个 import 命令以空行结束。对于每个 import 批处理，远程辅助程序应生成一个 fast-import 流，该流以 done 命令结束。

请注意，如果使用了 bidi-import 功能，则必须在开始将数据发送到 fast-import 之前缓冲完整的批处理序列，以防止命令和 fast-import 响应在辅助程序的 stdin 上混淆。

如果辅助程序具有“import”功能，则支持此命令。

export

指示远程辅助程序，任何后续输入都是 fast-import 流（由 git fast-export 生成）的一部分，其中包含应推送到远程的对象。

尤其适用于与外部版本控制系统进行互操作。

export-marks 和 import-marks 功能（如果已指定）会影响此命令，因为它们会被传递给 git fast-export，然后后者将加载/存储本地对象的 marks 表。这可用于实现增量操作。

如果辅助程序具有“export”功能，则支持此命令。

connect <service>

连接到指定的服务。辅助程序的标准输入和标准输出连接到远程端的指定服务（git 前缀包含在服务名称中，例如获取使用 git-upload-pack 作为服务）。此命令的有效响应为空行（连接已建立）、fallback（没有智能传输支持，回退到哑传输）以及仅显示错误消息并退出（无法连接，不要尝试回退）。在终止正面（空）响应的换行符之后，将开始显示服务的输出。连接结束后，远程辅助程序退出。

如果辅助程序具有“connect”功能，则支持此命令。

stateless-connect <service>

实验性功能；仅供内部使用。连接到指定的远程服务，以便使用 Git 的 wire-protocol 版本 2 进行通信。此命令的有效响应为空行（连接已建立）、fallback（没有智能传输支持，回退到哑传输）以及仅显示错误消息并退出（无法连接，不要尝试回退）。在终止正面（空）响应的换行符之后，将开始显示服务的输出。消息（请求和响应）必须由零个或多个 PKT-LINE 组成，并以 flush packet 结束。响应消息在 flush packet 之后将有一个 response end packet，以指示响应的结束。客户端不得期望服务器在请求-响应对之间存储任何状态。连接结束后，远程辅助程序退出。

如果辅助程序具有“stateless-connect”功能，则支持此命令。

get <uri> <path>

将文件从给定的 <uri> 下载到给定的 <path>。如果 <path>.temp 存在，则 Git 假定 .temp 文件是先前尝试的下载的未完成部分，并将从该位置恢复下载。

如果发生致命错误，程序会将错误消息写入 stderr 并退出。调用者应预期，如果子进程在未完成当前命令的有效响应的情况下关闭连接，则已打印合适的错误消息。

可能支持其他命令，具体取决于辅助程序报告的功能。

引用列表属性

list 命令生成一个引用列表，其中每个引用后面可能跟一个属性列表。以下引用列表属性已定义。

unchanged

此引用自上次导入或获取以来未发生更改，尽管辅助程序不一定能确定是哪个值产生了此结果。

引用列表关键字

list 命令可以生成键值对列表。以下关键字已定义。

object-format

引用使用给定的哈希算法。此关键字仅在服务器和客户端都支持 object-format 扩展时使用。

选项

以下选项已定义，并在（在适当的情况下）由 Git 设置，如果远程辅助程序具有 option 功能。

option verbosity <n>

更改辅助程序显示的邮件的详细程度。0 表示 <n>，意味着进程安静地运行，并且辅助程序仅产生错误输出。1 是默认的详细程度，<n> 值越高对应于命令行上传递的 -v 标志的数量。

option progress {true|false}

在命令期间启用（或禁用）传输辅助程序显示的进度消息。

option depth <depth>

加深浅层存储库的历史记录。

option deepen-since <timestamp>

根据时间加深浅层存储库的历史记录。

option deepen-not <ref>

加深浅层存储库的历史记录，排除 ref。多个选项累加。

option deepen-relative {true|false}

相对于当前边界加深浅层存储库的历史记录。仅当与“option depth”一起使用时有效。

option followtags {true|false}

如果启用，辅助程序应自动获取带注释的 tag 对象，前提是 tag 指向的对象在 fetch 命令期间被传输。如果辅助程序未获取 tag，通常会发送第二个 fetch 命令来专门请求该 tag。某些辅助程序可以使用此选项来避免第二次网络连接。

option dry-run {true|false}

如果为 true，则假装操作成功完成，但实际上不更改任何存储库数据。对于大多数辅助程序，这仅适用于 push（如果受支持）。

option servpath <c-style-quoted-path>

设置下一个 connect 请求的服务路径（--upload-pack、--receive-pack 等）。远程辅助程序可能支持此选项，但不应依赖于在 connect 请求发生之前设置此选项。

option check-connectivity {true|false}

请求辅助程序检查克隆的连通性。

option force {true|false}

请求辅助程序执行强制更新。默认为 false。

option cloning {true|false}

通知辅助程序这是一个克隆请求（即当前存储库保证为空）。

option update-shallow {true|false}

允许扩展 .git/shallow，如果新的引用需要的话。

option pushcert {true|false}

GPG 签名推送。

option push-option <string>

将 <string> 作为推送选项传输。由于推送选项不得包含 LF 或 NUL 字符，因此字符串不会被编码。

option from-promisor {true|false}

表示这些对象是从 promisor 获取的。

option no-dependents {true|false}

表示只需要获取所需的那些对象，而不需要它们的依赖项。

option atomic {true|false}

推送时，请求远程服务器在一个原子事务中更新引用。如果成功，所有引用都将被更新；否则，一个都不会。如果远程端不支持此功能，则推送将失败。

option object-format true

表示调用者希望将哈希算法信息从远程端传回。此模式在获取引用时使用。

另请参阅

git-remote[1]

git-remote-ext[1]

git-remote-fd[1]

git-fast-import[1]

GIT

Git[1] 套件的一部分