English ▾ 主题 ▾ 最新版本 ▾ gitremote-helpers 上次更新于 2.45.0

名称

gitremote-helpers - 用于与远程仓库交互的辅助程序

概要

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

描述

远程辅助程序通常不被最终用户直接使用，而是当 Git 需要与 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> 是它本身无法处理的协议，它会自动使用完整 URL 作为第二个参数调用 git remote-<transport>。如果在命令行上直接遇到此类 URL，则第一个参数与第二个参数相同，如果在配置的远程仓库中遇到，则第一个参数是该远程仓库的名称。

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

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

输入格式

Git 在标准输入上向远程辅助程序发送命令列表，每行一个命令。第一个命令始终是 capabilities 命令，作为响应，远程辅助程序必须打印它支持的功能列表（参见下文），后跟一个空行。对 capabilities 命令的响应决定了 Git 在命令流的其余部分中使用的命令。

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

功能

每个远程辅助程序都应仅支持命令的子集。辅助程序支持的操作在对 capabilities 命令的响应中声明给 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 将尽可能使用它，如果在连接时辅助程序请求，则回退到其他功能（请参见命令下的 connect 命令）。在 push 和 export 之间进行选择时，Git 优先选择 push。其他前端可能具有一些其他的优先级顺序。

no-private-update

当使用 refspec 功能时，git 通常会在成功推送后更新私有引用。当 remote-helper 声明功能 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

可以保证在请求克隆时，接收到的包是自包含且已连接的。

get

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

如果辅助程序声明了 connect，Git 将尽可能使用它，如果在连接时辅助程序请求，则回退到其他功能（请参见命令下的 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 *:*。

在为去中心化版本控制系统编写 remote-helper 时，建议保留一个与本地仓库交互的本地副本，并让私有命名空间引用指向此本地仓库，而 refs/remotes 命名空间用于跟踪远程仓库。

bidi-import

此功能修改了 import 功能。remote-helper 可以使用 fast-import 命令 cat-blob 和 ls 来检索有关已存在于 fast-import 内存中的 blob 和 tree 的信息。这需要一个从 fast-import 到 remote-helper 的通道。如果除了 "import" 之外还声明了此功能，Git 将建立一个从 fast-import 到 remote-helper 的 stdin 的管道。由此可见，Git 和 fast-import 都连接到 remote-helper 的 stdin。由于 Git 可以向 remote-helper 发送多个命令，因此使用 bidi-import 的 helper 需要缓冲一个批处理中的所有 import 命令，然后再将数据发送到 fast-import。这是为了防止在 helper 的 stdin 上混合命令和 fast-import 响应。

export-marks <文件>

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

import-marks <文件>

此功能修改了 export 功能，指示 Git 在处理任何输入之前加载 <文件> 中指定的标记。有关详细信息，请阅读 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

这表明 helper 能够使用显式哈希算法扩展与远程端交互。

命令

调用者在 helper 的标准输入上给出命令，每行一个。

capabilities

列出 helper 的功能，每行一个，以空行结尾。每个功能前面可以加上 *，这表示对于使用 remote helper 的 Git 版本来说，它们是必须理解的。任何未知的强制性功能都是致命错误。

必须支持此命令。

list

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

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

如果 helper 具有 "fetch" 或 "import" 功能，则支持此命令。

list for-push

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

如果 helper 具有 "push" 或 "export" 功能，则支持此命令。

option <名称> <值>

将传输 helper 选项 <名称> 设置为 <值>。输出一行，包含 ok（选项已成功设置）、unsupported（无法识别选项）或 error <msg>（支持选项 <名称>，但 <值> 对其无效）之一。应在其他命令之前设置选项，并且选项可能会影响这些命令的行为。

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

如果 helper 具有 "option" 功能，则支持此命令。

fetch <sha1> <名称>

获取给定的对象，并将必要的对象写入数据库。Fetch 命令以批处理形式发送，每行一个，以空行结尾。当同一批处理中的所有 fetch 命令都完成时，输出一个空行。只有在 list 的输出中报告了 sha1 的对象才能以这种方式获取。

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

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

如果 helper 具有 "fetch" 功能，则支持此命令。

push +<src>:<dst>

将给定的本地 <src> 提交或分支推送到 <dst> 描述的远程分支。一个或多个 push 命令的批处理序列以空行结尾（如果只有一个引用要推送，则单个 push 命令后跟一个空行）。例如，以下将是两批 push，第一批要求 remote-helper 将本地引用 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 样式字符串引用它。

如果 helper 具有 "push" 功能，则支持此命令。

import <名称>

生成一个 fast-import 流，该流导入命名引用的当前值。它还可以根据需要导入其他引用，以有效地构造历史记录。该脚本写入 helper 特定的私有命名空间。命名引用的值应写入此命名空间中的一个位置，该位置是通过将 "refspec" 功能中的 refspec 应用于引用的名称派生的。

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

就像 push 一样，一个或多个 import 的批处理序列以空行结尾。对于每批 import，remote helper 应生成一个以 done 命令结尾的 fast-import 流。

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

如果 helper 具有 "import" 功能，则支持此命令。

export

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

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

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

如果 helper 具有 "export" 功能，则支持此命令。

connect <服务>

连接到给定的服务。helper 的标准输入和标准输出连接到远程端上指定的服务（git 前缀包含在服务名称中，因此例如，获取使用 git-upload-pack 作为服务）。对此命令的有效回复是空行（已建立连接）、fallback（没有智能传输支持，回退到 dumb 传输）以及仅打印错误消息退出（无法连接，无需费心尝试回退）。在终止肯定（空）响应的换行符之后，服务的输出开始。连接结束后，remote helper 退出。

如果 helper 具有 "connect" 功能，则支持此命令。

stateless-connect <服务>

实验性的；仅供内部使用。连接到给定的远程服务，以使用 git 的 wire-protocol version 2 进行通信。对此命令的有效回复是空行（已建立连接）、fallback（没有智能传输支持，回退到 dumb 传输）以及仅打印错误消息退出（无法连接，无需费心尝试回退）。在终止肯定（空）响应的换行符之后，服务的输出开始。消息（请求和响应）必须由零个或多个 PKT-LINE 组成，以刷新包结尾。然后，响应消息将在刷新包之后具有响应结束包，以指示响应的结束。客户端不应期望服务器在请求-响应对之间存储任何状态。连接结束后，remote helper 退出。

如果 helper 具有 "stateless-connect" 功能，则支持此命令。

get <uri> <path>

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

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

可以支持其他命令，这可以根据 helper 报告的功能来确定。

引用列表属性

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

unchanged (未更改)

自上次导入或抓取以来，此引用未更改，尽管帮助程序不一定能确定产生的值。

引用列表关键字

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

object-format (对象格式)

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

选项

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

option verbosity <n> (选项 verbosity <n>)

更改帮助程序显示的消息的详细程度。 <n> 值为 0 表示进程静默运行，帮助程序仅生成错误输出。 1 是默认详细程度，<n> 的较高值对应于命令行上传递的 -v 标志的数量。

option progress {true|false} (选项 progress {true|false})

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

option depth <depth> (选项 depth <depth>)

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

option deepen-since <timestamp> (选项 deepen-since <timestamp>)

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

option deepen-not <ref> (选项 deepen-not <ref>)

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

option deepen-relative {true|false} (选项 deepen-relative {true|false})

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

option followtags {true|false} (选项 followtags {true|false})

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

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

option servpath <c-style-quoted-path> (选项 servpath <c-style-quoted-path>)

为下一次连接设置服务路径（--upload-pack, --receive-pack 等）。远程帮助程序可以支持此选项，但不得依赖于在connect请求发生之前设置此选项。

option check-connectivity {true|false} (选项 check-connectivity {true|false})

请求帮助程序检查克隆的连接性。

option force {true|false} (选项 force {true|false})

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

option cloning {true|false} (选项 cloning {true|false})

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

option update-shallow {true|false} (选项 update-shallow {true|false})

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

option pushcert {true|false} (选项 pushcert {true|false})

GPG 签名推送。

option push-option <string> (选项 push-option <string>)

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

option from-promisor {true|false} (选项 from-promisor {true|false})

指示这些对象是从承诺者那里获取的。

option no-dependents {true|false} (选项 no-dependents {true|false})

指示只需要获取想要的对象，而不是它们的依赖项。

option atomic {true|false} (选项 atomic {true|false})

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

option object-format true (选项 object-format true)

指示调用者希望将哈希算法信息从远程传递回来。 当抓取引用时使用此模式。

另请参阅

git-remote[1]

git-remote-ext[1]

git-remote-fd[1]

git-fast-import[1]

GIT

git[1] 套件的一部分

scroll-to-top