Git sends the remote helper a list of commands on standard input,
one per line. The first command is always the capabilities
command, in response to which the remote helper must print a list
of the capabilities it supports (see below) followed by a blank
line. The response to the capabilities command determines what
commands Git uses in the remainder of the command stream.
The command stream is terminated by a blank line. In some cases
(indicated in the documentation of the relevant commands), this
blank line is followed by a payload in some other protocol (e.g.,
the pack protocol), while in others it indicates the end of
input.
Capabilities
Each remote helper is expected to support only a subset of
commands. The operations a helper supports are declared to Git in
the response to the capabilities command (see COMMANDS, below).
In the following, we list all defined capabilities and for each
we list which commands a helper with that capability must
provide.
Capabilities for Pushing
connect
Can attempt to connect to git receive-pack (for pushing),
git upload-pack, etc for communication using git's native
packfile protocol. This requires a bidirectional,
full-duplex connection.
Supported commands: connect.
stateless-connect
Experimental; for internal use only. Can attempt to
connect to a remote server for communication using git's
wire-protocol version 2. See the documentation for the
stateless-connect command for more information.
Supported commands: stateless-connect.
push
Can discover remote refs and push local commits and the
history leading up to them to new or existing remote
refs.
Supported commands: list for-push, push.
export
Can discover remote refs and push specified objects from
a fast-import stream to remote refs.
Supported commands: list for-push, export.
If a helper advertises connect, Git will use it if possible
and fall back to another capability if the helper requests so
when connecting (see the connect command under COMMANDS).
When choosing between push and export, Git prefers push.
Other frontends may have some other order of preference.
no-private-update
When using the refspec capability, git normally updates
the private ref on successful push. This update is
disabled when the remote-helper declares the capability
no-private-update.
Capabilities for Fetching
connect
Can try to connect to git upload-pack (for fetching), git
receive-pack, etc for communication using the Git's
native packfile protocol. This requires a bidirectional,
full-duplex connection.
Supported commands: connect.
stateless-connect
Experimental; for internal use only. Can attempt to
connect to a remote server for communication using git's
wire-protocol version 2. See the documentation for the
stateless-connect command for more information.
Supported commands: stateless-connect.
fetch
Can discover remote refs and transfer objects reachable
from them to the local object store.
Supported commands: list, fetch.
import
Can discover remote refs and output objects reachable
from them as a stream in fast-import format.
Supported commands: list, import.
check-connectivity
Can guarantee that when a clone is requested, the
received pack is self contained and is connected.
If a helper advertises connect, Git will use it if possible
and fall back to another capability if the helper requests so
when connecting (see the connect command under COMMANDS).
When choosing between fetch and import, Git prefers fetch.
Other frontends may have some other order of preference.
Miscellaneous capabilities
option
For specifying settings like verbosity (how much output
to write to stderr) and depth (how much history is wanted
in the case of a shallow clone) that affect how other
commands are carried out.
refspec <refspec>
For remote helpers that implement import or export, this
capability allows the refs to be constrained to a private
namespace, instead of writing to refs/heads or
refs/remotes directly. It is recommended that all
importers providing the import capability use this. It's
mandatory for export.
A helper advertising the capability refspec
refs/heads/*:refs/svn/origin/branches/* is saying that,
when it is asked to import refs/heads/topic, the stream
it outputs will update the refs/svn/origin/branches/topic
ref.
This capability can be advertised multiple times. The
first applicable refspec takes precedence. The left-hand
of refspecs advertised with this capability must cover
all refs reported by the list command. If no refspec
capability is advertised, there is an implied refspec
*:*.
When writing remote-helpers for decentralized version
control systems, it is advised to keep a local copy of
the repository to interact with, and to let the private
namespace refs point to this local repository, while the
refs/remotes namespace is used to track the remote
repository.
bidi-import
This modifies the import capability. The fast-import
commands cat-blob and ls can be used by remote-helpers to
retrieve information about blobs and trees that already
exist in fast-import's memory. This requires a channel
from fast-import to the remote-helper. If it is
advertised in addition to "import", Git establishes a
pipe from fast-import to the remote-helper's stdin. It
follows that Git and fast-import are both connected to
the remote-helper's stdin. Because Git can send multiple
commands to the remote-helper it is required that helpers
that use bidi-import buffer all import commands of a
batch before sending data to fast-import. This is to
prevent mixing commands and fast-import responses on the
helper's stdin.
export-marks <file>
This modifies the export capability, instructing Git to
dump the internal marks table to <file> when complete.
For details, read up on --export-marks=<file> in
git-fast-export(1).
import-marks <file>
This modifies the export capability, instructing Git to
load the marks specified in <file> before processing any
input. For details, read up on --import-marks=<file> in
git-fast-export(1).
signed-tags
This modifies the export capability, instructing Git to
pass --signed-tags=verbatim to git-fast-export(1). In the
absence of this capability, Git will use
--signed-tags=warn-strip.
object-format
This indicates that the helper is able to interact with
the remote side using an explicit hash algorithm
extension.
