gitremote helpers

命名

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 遇到一个表单的 URL <transport>://<address>，其中<transport>是一个它本身无法处理的协议，它会自动调用git remote-<transport>完整的 URL 作为第二个参数。如果直接在命令行中遇到这样的 URL ，那么第一个参数与第二个参数相同，如果在配置的远程中遇到，则第一个参数是该远程的名称。

该表单的 URL <transport>::<address>明确指示 Git git remote-<transport>使用<address>第二个参数。如果在命令行上直接遇到这样的 URL ，那么第一个参数是<address>，如果在配置的远程中遇到，则第一个参数是该远程的名称。

另外，当配置的远程已经remote.<name>.vcs设置为<transport>，GIT 中明确地调用git remote-<transport>与<name>作为第一个参数。如果设置，第二个参数是remote.<name>.url; 否则，第二个参数被省略。

输入格式

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

命令流由空行终止。在某些情况下（在相关命令的文档中指出），该空行后面是其他协议中的有效载荷（例如包协议），而在其他情况下则表示输入结束。

功能

预计每个远程助手只支持一部分命令。辅助程序支持的操作在对capabilities命令的响应中声明为 Git （请参见下面的 COMMANDS ）。

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

推动能力

connect

可以尝试使用 git 的本机 packfile 协议连接git receive-pack（推送）git upload-pack等通信。这需要双向全双工连接。

支持的命令：connect。

push

可以发现远程引用，并将本地提交以及引导给它们的历史推送到新的或现有的远程引用。

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

export

可以发现远程引用，并将快速导入流中的指定对象推送到远程引用。

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

如果给connect打广告，Git 将尽可能使用它，如果助手在连接时请求，则会回退到另一个能力（请参阅connect COMMANDS 下的命令）。当选择push和export，Git 喜欢push。其他前端可能有其他一些优先顺序。

no-private-update

在使用该refspec功能时，git 通常会在成功推送时更新私有的参考。当 remote-helper 声明能力时，此更新被禁用no-private-update。

提取能力

connect

可以尝试使用 Git 的本机 packfile 协议连接git upload-pack（用于读取）git receive-pack等。这需要双向全双工连接。

支持的命令：connect。

fetch

可以发现远程引用并将可从其访问的对象传输到本地对象存储区。

Supported commands: list, fetch.

import

可以发现远程引用并将它们可访问的对象以快速导入格式输出为流。

支持的命令：list，import。

check-connectivity

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

如果 helper 做广告connect，Git 将尽可能使用它，如果助手在连接时请求，则会回退到另一个能力（请参阅connect COMMANDS 下的命令）。当选择fetch和import，Git 喜欢fetch。其他前端可能有其他一些优先顺序。

杂项功能

option

用于指定像verbosity（写入 stderr 的输出量有多少）和depth（对浅克隆而言需要多少历史记录）等影响其他命令执行的设置。

refspec <refspec>

对于实现import或者的远程助手export，这个功能允许 refs 被限制到一个私有名称空间，而不是直接写入 refs / heads 或者 ref / remotes 。建议所有提供此import功能的进口商都使用此功能。这是强制性的export。

refspec refs/heads/*:refs/svn/origin/branches/*，当它被要求时import refs/heads/topic，它输出的流将更新refs/svn/origin/branches/topic参考。

此功能可以被多次建议。第一个适用的 refspec 优先。使用此功能宣传的 refspecs 的左侧必须覆盖 list 命令报告的所有参考。如果没有refspec能力被宣传，那就暗示了refspec *:*。

当为分散版本控制系统编写 remote-helpers 时，建议保留一个本地的版本库副本进行交互，并让私有命名空间参考指向这个本地版本库，而 refs / remotes 命名空间用于跟踪远程存储库。

bidi-import

这改变了import能力。快速导入命令cat-blob，ls远程助手可以使用该命令来检索快速导入内存中已存在的斑点和树的信息。这需要一个从快速导入到远程助手的通道。如果除了“导入”之外还公布了它，Git 将建立一个从快速导入到远程助手 stdin 的管道。因此，Git 和快速导入都连接到远程助手的 stdin 。因为 Git 可以向远程帮助器发送多个命令，所以需要使用bidi-import缓冲区的帮助器import在发送数据到快速导入之前使用缓冲区的所有命令。这是为了防止在助手的 stdin 上混合命令和快速导入响应。

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。

命令

命令由调用者在助手的标准输入中给出，每行一个。

capabilities

列出助手的功能，每行一个，以空行结束。每个功能都可以使用*，这标志着它们对于使用远程帮助程序理解的 Git 版本是强制性的。任何未知的强制性能力都是致命的错误。

对此命令的支持是强制性的。

list

以 “<value> <name> <attr> ...” 格式列出每行一个参考。值可以是一个十六进制 sha1 散列，“@ <dest>” 用于 symref或 “？” 以表明助手无法获得参考价值。名称后面有空格分隔的属性列表; 无法识别的属性被忽略。该列表以空行结束。

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

如果助手具有“获取”或“导入”功能，则受支持。

list for-push

list与之类似，只是当且仅当调用者想要生成的引用列表准备推送命令时才使用它。同时支持 push 和 fetch 的助手可以使用它来区分list将要使用输出的操作，可能会减少需要执行的工作量。

如果助手具有“推送”或“导出”功能，则支持该功能。

option <name> <value>

将传输助手选项 <name> 设置为 <value> 。输出包含ok（选项成功设置），unsupported（选项无法识别）和error <msg>（选项 <name> 支持但 <value> 无效）之一的单行。选项应在其他命令之前设置，并可能影响这些命令的行为。

请参阅选项以获取当前定义的选项列表。

如果助手具有“选项”功能则支持。

fetch <sha1> <name>

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

也可以输出一个lock <file>指示 GIT_DIR / objects / pack 下的文件的行，该文件保持一个包，直到 ref 可以被适当地更新。

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

如果助手具有“获取”功能，则受支持。

push +<src>:<dst>

将给定的本地 <src> 提交或分支推送到由 <dst> 描述的远程分支。一个或多个push命令的批处理序列以空行结束（如果只有一个引用来推送，则单个push命令后面跟着一个空行）。例如，下面是两批push，第一批要求 remote-helper 将本地 ref推master送到远程 ref master，将本地 ref 推HEAD送到远程branch，第二批要求将 ref 推入fooref 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>?线路以指示每个推送参考的成功或失败。状态报告输出以空行结束。如果选项字段包含 LF，则可以用 C 风格字符串引用该选项字段。

如果助手具有 "push" 功能则支持。

import <name>

生成一个快速导入的流，导入指定 ref 的当前值。它还可以根据需要额外导入其他参考以高效地构建历史记录。脚本写入助手特定的私有名称空间。named ref 的值应写入此名称空间中的一个位置，该位置通过将 refspecs 从 “refspec” 功能应用到 ref 的名称而得出。

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

就像push，一个或多个批处理序列import以空行结束。对于每一批import，远程助手应该产生一个由done命令终止的快速导入流。

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

如果助手具有 "import" 功能则支持。

export

指示远程助手任何后续输入都是快速导入流（由生成的git fast-export）的一部分，该流包含应推送到远程的对象。

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

如果指定了这些export-marks和import-marks功能，只要它们被传递到git fast-export，就会影响此命令，然后它会为本地对象加载/存储一个标记表。这可以用于执行增量操作。

如果助手具有“导出”功能则支持。

connect <service>

连接到给定的服务。帮助器的标准输入和标准输出连接到指定服务（git 前缀包含在服务名称中，例如，git-upload-pack作为服务提取使用）在远程端。对此命令的有效答复是空行（已建立连接），fallback（不支持智能传输支持，退回到哑传输），并且仅在退出时显示错误消息（无法连接，请勿尝试退回）。在换行终止正（空）响应后，服务输出开始。连接结束后，远程助手退出。

如果助手具有 "connect" 功能则支持。

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

可以支持附加的命令，这可以从助手报告的能力中确定。

参考列表属性

该list命令产生一个 ref 列表，其中每个 ref 可以后跟一个属性列表。定义了以下参考列表属性。

unchanged

该引用自上次导入或提取后不变，但助手不一定能确定产生的值。

选项

如果远程助手有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 followtags {true|false}

如果启用，助手应自动获取带注释的标签对象，如果标签指向的对象在获取命令期间被传送。如果标签没有被助手获取，通常会发送第二个获取命令来特别要求标签。一些助手可能能够使用此选项来避免第二次网络连接。

option dry-run{ true| false}：如果为 true ，则假装操作成功完成，但实际上并未更改任何存储库数据。对于大多数帮助者来说，这只适用于push（如果支持的话）。

option servpath <c-style-quoted-path>

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

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 字符，因此字符串不会被编码。