简体中文 ▾ 主题 ▾ 最新版本 ▾ gitremote-helpers 最后更新于 2.45.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 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 命令的响应中声明给 Git（见下面的 COMMANDS）。

在下文中，我们列出了所有定义的功能，并为每个功能列出了具有该功能的辅助程序必须提供的命令。

推送功能

connect

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

支持的命令：connect。

stateless-connect

实验性；仅供内部使用。可以尝试连接到远程服务器，以使用 Git 的线协议版本 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 的线协议版本 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 命令。这是为了防止在辅助程序的 stdin 上混合命令和 fast-import 响应。

export-marks <file>

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

import-marks <file>

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

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 哈希值，symref 的“@<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>

抓取给定对象，将必要的对象写入数据库。抓取命令以批处理方式发送，每行一个，以空行终止。当同一批次中的所有抓取命令完成后，输出一个空行。只有在 list 输出中报告了 SHA1 的对象才能以这种方式抓取。

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

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

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

push +<src>:<dst>

将给定的本地 <src> 提交或分支推送到 <dst> 所描述的远程分支。一个或多个 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 批次，远程辅助程序应生成一个以 done 命令终止的 fast-import 流。

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

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

export

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

对于与外部版本控制系统互操作特别有用。

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

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

connect <service>

连接到给定服务。辅助程序的标准输入和标准输出连接到远程侧的指定服务（服务名称中包含 Git 前缀，例如抓取使用 *git-upload-pack* 作为服务）。对此命令的有效回复为空行（连接已建立）、*fallback*（不支持智能传输，回退到哑传输）以及直接退出并打印错误消息（无法连接，无需尝试回退）。在终止肯定（空）响应的换行符之后，服务输出开始。连接结束后，远程辅助程序退出。

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

stateless-connect <service>

实验性；仅供内部使用。连接到给定的远程服务，使用 Git 的线协议版本 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 扩展时使用。

选项

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

option verbosity <n>

更改辅助程序显示消息的详细程度。对于 <n>，值为 0 意味着进程安静运行，辅助程序只产生错误输出。1 是默认的详细级别，<n> 的较高值对应于命令行上传递的 -v 标志的数量。

option progress {true|false}

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

option depth <depth>

加深浅仓库的历史。

option deepen-since <timestamp>

根据时间加深浅仓库的历史。

option deepen-not <ref>

加深浅仓库的历史，排除引用。多个选项叠加。

option deepen-relative {true|false}

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

option followtags {true|false}

如果启用，辅助程序应在抓取命令期间传输标签指向的对象时，自动抓取带注释的标签对象。如果辅助程序未抓取标签，通常会发送第二个抓取命令以专门请求该标签。一些辅助程序可能能够使用此选项来避免第二次网络连接。

option dry-run {true|false}：如果为 true，则假装操作成功完成，但实际上不更改任何仓库数据。对于大多数辅助程序，这仅适用于 push（如果支持）。

option servpath <c-style-quoted-path>

为下一次连接设置服务路径（--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] 套件的一部分

scroll-to-top