设置和配置
获取和创建项目
基本快照
分支和合并
共享和更新项目
检查和比较
修补
调试
电子邮件
外部系统
服务器管理员
指南
管理
管道命令
- 2.38.1 → 2.44.0 无更改
-
2.38.0
10/02/22
- 2.28.1 → 2.37.7 无更改
-
2.28.0
07/27/20
描述
远程帮助程序通常不会被终端用户直接使用，但当 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 以 <address> 作为第二个参数调用 git remote-<transport>。如果在命令行上直接遇到此类 URL，第一个参数为 <address>，如果在已配置的远程中遇到，第一个参数为该远程的名称。
此外，当已配置的远程将 remote.<name>.vcs 设置为 <transport> 时，Git 会明确以 <name> 作为第一个参数调用 git remote-<transport>。如果已设置，第二个参数为 remote.<name>.url；否则，将省略第二个参数。
输入格式
Git 通过标准输入向远程助手发送命令列表，每行一个命令。第一个命令始终是 capabilities 命令，作为响应，远程助手必须打印它支持的功能列表（见下文），后跟一个空行。对 capabilities 命令的响应决定了 Git 在命令流的其余部分中使用的命令。
命令流以空行终止。在某些情况下（在相关命令的文档中指出），此空行后跟其他协议中的有效负载（例如，包协议），而在其他情况下，它表示输入结束。
功能
每个远程助手预计仅支持一部分命令。助手支持的操作在对 capabilities 命令的响应中向 Git 声明（见下文的命令）。
在以下内容中，我们列出了所有已定义的功能，并为每个功能列出了具有该功能的助手必须提供的命令。
推送功能
- connect
-
可以尝试连接到 git receive-pack（用于推送）、git upload-pack 等，以使用 Git 的原生包文件协议进行通信。这需要一个双向全双工连接。
支持的命令：connect。
- stateless-connect
-
实验性；仅供内部使用。可以尝试使用 Git 的线协议版本 2 连接到远程服务器进行通信。有关详细信息，请参阅 stateless-connect 命令的文档。
支持的命令：stateless-connect。
- push
-
可以发现远程引用并推送本地提交以及导致新或现有远程引用的历史记录。
支持的命令：list for-push、push。
- 导出
-
可以发现远程引用，并将指定的对象从快速导入流推送到远程引用。
支持的命令：list for-push、export。
如果辅助程序通告connect，Git 将在可能的情况下使用它，并在连接时辅助程序请求时退回到其他功能（请参阅 COMMANDS 下的connect 命令）。在push 和export 之间进行选择时，Git 优先选择push。其他前端可能有一些其他优先顺序。
用于获取的功能
- connect
-
可以尝试连接到git upload-pack（用于获取）、git receive-pack 等，以使用 Git 的原生 packfile 协议进行通信。这需要一个双向、全双工连接。
支持的命令：connect。
- stateless-connect
-
实验性；仅供内部使用。可以尝试使用 Git 的线协议版本 2 连接到远程服务器进行通信。有关详细信息，请参阅 stateless-connect 命令的文档。
支持的命令：stateless-connect。
- fetch
-
可以发现远程引用，并将可以从这些引用访问的对象传输到本地对象存储。
支持的命令：list、fetch。
- import
-
可以发现远程引用，并将可以从这些引用访问的对象作为快速导入格式的流输出。
支持的命令：list、import。
- check-connectivity
-
可以保证在请求克隆时，接收的包是自包含且已连接的。
- get
-
可以使用get 命令从给定的 URI 下载文件。
如果辅助程序通告connect，Git 将在可能的情况下使用它，并在连接时辅助程序请求时退回到其他功能（请参阅 COMMANDS 下的connect 命令）。在fetch 和import 之间进行选择时，Git 优先选择fetch。其他前端可能有一些其他优先顺序。
其他功能
- 选项
-
用于指定影响其他命令执行方式的设置，例如
verbosity（向 stderr 写入的输出量）和depth（浅层克隆情况下所需的历史记录量）。 - refspec <refspec>
-
对于实现导入或导出的远程助手，此功能允许将 ref 限制到专用命名空间，而不是直接写入 refs/heads 或 refs/remotes。建议所有提供导入功能的导入器都使用此功能。对于导出功能，此功能是必需的。
通告功能
refspec refs/heads/*:refs/svn/origin/branches/*的助手表示，当它被要求导入 refs/heads/topic时，它输出的流将更新refs/svn/origin/branches/topicref。此功能可以通告多次。第一个适用的 refspec 优先。使用此功能通告的 refspec 的左侧必须涵盖列表命令报告的所有 ref。如果没有通告refspec 功能，则隐含
refspec *:*。为分散版本控制系统编写远程助手时，建议保留要交互的存储库的本地副本，并让专用命名空间 ref 指向此本地存储库，而 refs/remotes 命名空间用于跟踪远程存储库。
- bidi-import
-
这修改了导入功能。远程助手可以使用快速导入命令cat-blob 和 ls 来检索有关已存在于快速导入内存中的 blob 和树的信息。这需要从快速导入到远程助手的通道。如果除了“导入”之外还通告了此功能，Git 会建立从快速导入到远程助手 stdin 的管道。这意味着 Git 和快速导入都连接到远程助手的 stdin。由于 Git 可以向远程助手发送多个命令，因此要求使用bidi-import 的助手在向快速导入发送数据之前缓冲一批中的所有导入命令。这是为了防止在助手的 stdin 上混合命令和快速导入响应。
- export-marks <file>
-
这修改了导出功能，指示 Git 在完成时将内部标记表转储到 <file>。有关详细信息，请参阅 git-fast-export[1] 中的
--export-marks=<file>。 - import-marks <file>
-
这修改了导出功能，指示 Git 在处理任何输入之前加载 <file> 中指定的标记。有关详细信息，请参阅 git-fast-export[1] 中的
--import-marks=<file>。 - signed-tags
-
这修改了导出功能，指示 Git 将
--signed-tags=verbatim传递给 git-fast-export[1]。如果没有此功能，Git 将使用--signed-tags=warn-strip。 - object-format
-
这表示助手能够使用显式哈希算法扩展与远程端交互。
命令
命令由调用者在助手的标准输入上给出，每行一个。
- capabilities
-
列出助手的功能，每行一个，以空行结尾。每个功能前面都可以加上 *，这表示它们对于使用远程助手理解 Git 版本是必需的。任何未知的必需功能都是致命错误。
对该命令的支持是必需的。
- list
-
列出 ref，每行一个，格式为“<value> <name> [<attr> …]”。该值可以是十六进制 sha1 哈希，“@<dest>”表示 symref，“:<keyword> <value>”表示键值对，或“?”表示助手无法获取 ref 的值。名称后跟一个空格分隔的属性列表；忽略无法识别的属性。该列表以空行结尾。
请参阅 REF LIST ATTRIBUTES 以获取当前定义的属性列表。请参阅 REF LIST KEYWORDS 以获取当前定义的关键字列表。
如果助手具有“fetch”或“import”功能，则支持。
- list for-push
-
类似于 list，但仅在调用者希望生成 ref 列表以准备推送命令时使用。同时支持推送和获取的帮助程序可以使用它来区分 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下文件的完整路径，该文件保留一个包，直到 ref 可以适当更新。路径必须以.keep结尾。这是一种通过仅提供 keep 组件来命名 <pack,idx,keep> 元组的机制。即使其对象可能在获取完成之前未被引用，保留的包也不会被并发重新打包删除。.keep文件将在获取结束时删除。如果请求选项 check-connectivity，则如果克隆是自包含且已连接，帮助程序必须输出 connectivity-ok。
如果帮助程序具有“fetch”功能，则支持。
- push +<src>:<dst>
-
将给定的本地 <src> 提交或分支推送到 <dst> 描述的远程分支。由一个或多个 push 命令组成的批次序列以空行终止（如果只有一个要推送的引用，则单个 push 命令后跟一个空行）。例如，以下内容将是两批 push，第一批要求远程帮助程序将本地 ref master 推送到远程 ref master，并将本地
HEAD推送到远程 branch，第二批要求将 ref foo 推送到 ref 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>? 行，以指示每个推送 ref 的成功或失败。状态报告输出以空行终止。如果选项字段 <why> 包含 LF，则可以用 C 样式字符串引用它。
如果助手具有“push”功能，则受支持。
- import <name>
-
生成一个快速导入流，用于导入指定 ref 的当前值。它还可以根据需要导入其他 ref，以有效地构建历史记录。脚本写入助手特定的私有命名空间。指定 ref 的值应写入该命名空间中的某个位置，该位置是通过将“refspec”功能中的 refspec 应用到 ref 的名称而派生的。
特别适用于与外部版本控制系统互操作。
就像push一样，一个或多个import的批处理序列以空行终止。对于每个import批处理，远程助手应生成一个以done命令终止的快速导入流。
请注意，如果使用了bidi-import功能，则必须在开始向快速导入发送数据之前缓冲完整的批处理序列，以防止在助手的标准输入上混合命令和快速导入响应。
如果助手具有“import”功能，则受支持。
- export
-
指示远程助手任何后续输入都是快速导入流（由git fast-export生成）的一部分，其中包含应推送到远程的对象。
特别适用于与外部版本控制系统互操作。
如果指定了export-marks和import-marks功能，它们会影响此命令，因为它们会传递给git fast-export，然后git fast-export会加载/存储本地对象的标记表。这可用于实现增量操作。
如果助手具有“export”功能，则受支持。
- connect <service>
-
连接到给定的服务。助手的标准输入和标准输出连接到远程端的指定服务（服务名称中包含 git 前缀，例如获取使用git-upload-pack作为服务）。对该命令的有效答复是空行（建立连接）、fallback（不支持智能传输，退回到哑传输）以及仅退出并打印错误消息（无法连接，不要尝试回退）。在终止肯定（空）响应的换行符后，服务的输出开始。连接结束后，远程助手退出。
如果助手具有“connect”功能，则受支持。
- stateless-connect <service>
-
实验性；仅供内部使用。使用 git 的线协议版本 2 连接到给定的远程服务进行通信。对该命令的有效答复是空行（建立连接）、fallback（不支持智能传输，退回到哑传输）以及仅退出并打印错误消息（无法连接，不要尝试回退）。在终止肯定（空）响应的换行符后，服务的输出开始。消息（请求和响应）必须由零个或多个 PKT-LINE 组成，并以刷新包终止。然后，响应消息将在刷新包之后有一个响应结束包，以指示响应的结束。客户端不应期望服务器在请求-响应对之间存储任何状态。连接结束后，远程助手退出。
如果助手具有“无状态连接”功能，则支持。
- get <uri> <path>
-
将文件从给定的
<uri>下载到给定的<path>。如果<path>.temp存在，则 Git 假设.temp文件是从先前尝试部分下载的，并将从该位置恢复下载。
如果发生致命错误，程序会将错误消息写入 stderr 并退出。如果子进程关闭连接而不为当前命令完成有效响应，则调用方应预期已打印出合适的错误消息。
可以支持其他命令，这可以通过助手报告的功能来确定。
OPTIONS
定义了以下选项，如果远程助手具有 option 功能，则 Git 会在（适当的情况下）设置这些选项。
- option verbosity <n>
-
更改助手显示的消息的详细程度。<n> 的值为 0 表示进程以静默方式操作，并且助手仅生成错误输出。1 是默认详细程度，<n> 的较高值对应于命令行中传递的 -v 标志的数量。
- option progress {true|false}
-
在命令期间启用（或禁用）传输助手显示的进度消息。
- option depth <depth>
-
加深浅层存储库的历史记录。
- 'option deepen-since <timestamp>
-
根据时间加深浅层存储库的历史记录。
- '选项 deepen-not <ref>
-
加深浅层存储库的历史记录，排除 ref。多个选项相加。
- 选项 deepen-relative {'true|false}
-
相对于当前边界加深浅层存储库的历史记录。仅在与“选项 depth”一起使用时有效。
- 选项 followtags {true|false}
-
如果启用，如果在获取命令期间传输了标签指向的对象，则帮助程序应自动获取带注释的标签对象。如果标签未被帮助程序获取，通常会发送第二个获取命令以专门请求该标签。一些帮助程序可能能够使用此选项来避免第二次网络连接。
选项 dry-run {true|false}：如果为 true，则假装操作已成功完成，但实际上不会更改任何存储库数据。对于大多数帮助程序，这仅适用于push（如果受支持）。
- 选项 servpath <c-style-quoted-path>
-
为下次连接设置服务路径（--upload-pack、--receive-pack 等）。远程帮助程序可能支持此选项，但不能依赖在连接请求发生之前设置此选项。
- 选项 check-connectivity {true|false}
-
请求帮助程序检查克隆的连接性。
- 选项 force {true|false}
-
请求帮助程序执行强制更新。默认为false。
- 选项 cloning {true|false}
-
通知帮助程序这是一个克隆请求（即当前存储库保证为空）。
- 选项 update-shallow {true|false}
-
如果新 ref 需要，允许扩展 .git/shallow。
- 选项 pushcert {true|false}
-
GPG 签名推送。
- '选项 push-option <string>
-
将 <string> 作为推送选项进行传输。由于推送选项不得包含 LF 或 NUL 字符，因此该字符串不会被编码。
- 选项 from-promisor {true|false}
-
表明这些对象正在从一个承诺者那里获取。
- 选项 no-dependents {true|false}
-
表明仅需要获取所需的那些对象，而不是它们的依赖项。
- 选项 atomic {true|false}
-
在推送时，请求远程服务器在单个原子事务中更新 ref。如果成功，所有 ref 都将被更新，否则没有一个 ref 会被更新。如果远程端不支持此功能，推送将失败。
- 选项 object-format {true|algorithm}
-
如果为 true，表明调用方希望从远程端传回哈希算法信息。此模式在获取 ref 时使用。
如果设置为一个算法，表明调用方希望使用该算法与远程端进行交互。
GIT
git[1] 套件的一部分
