Git - gitremote-helpers Documentation (2024)

Lists the capabilities of the helper, one per line, endingwith a blank line. Each capability may be preceded with *,which marks them mandatory for Git versions using the remotehelper to understand. Any unknown mandatory capability is afatal error.

Support for this command is mandatory.

Lists the refs, one per line, in the format "<value> <name>[<attr> …​]". The value may be a hex sha1 hash, "@<dest>" fora symref, ":<keyword> <value>" for a key-value pair, or"?" to indicate that the helper could not get the value of theref. A space-separated list of attributes follows the name;unrecognized attributes are ignored. The list ends with ablank line.

See REF LIST ATTRIBUTES for a list of currently defined attributes.See REF LIST KEYWORDS for a list of currently defined keywords.

Supported if the helper has the "fetch" or "import" capability.

Similar to list, except that it is used if and only ifthe caller wants to the resulting ref list to preparepush commands.A helper supporting both push and fetch can use thisto distinguish for which operation the output of listis going to be used, possibly reducing the amountof work that needs to be performed.

Supported if the helper has the "push" or "export" capability.

Sets the transport helper option <name> to <value>. Outputs asingle line containing one of ok (option successfully set),unsupported (option not recognized) or error <msg>(option <name> is supported but <value> is not validfor it). Options should be set before other commands,and may influence the behavior of those commands.

See OPTIONS for a list of currently defined options.

Supported if the helper has the "option" capability.

Fetches the given object, writing the necessary objectsto the database. Fetch commands are sent in a batch, oneper line, terminated with a blank line.Outputs a single blank line when all fetch commands in thesame batch are complete. Only objects which were reportedin the output of list with a sha1 may be fetched this way.

Optionally may output a lock <file> line indicating the full path ofa file under $GIT_DIR/objects/pack which is keeping a pack untilrefs can be suitably updated. The path must end with .keep. This isa mechanism to name a <pack,idx,keep> tuple by giving only the keepcomponent. The kept pack will not be deleted by a concurrent repack,even though its objects may not be referenced until the fetch completes.The .keep file will be deleted at the conclusion of the fetch.

If option check-connectivity is requested, the helper must outputconnectivity-ok if the clone is self-contained and connected.

Supported if the helper has the "fetch" capability.

Pushes the given local <src> commit or branch to theremote branch described by <dst>. A batch sequence ofone or more push commands is terminated with a blank line(if there is only one reference to push, a single push commandis followed by a blank line). For example, the following wouldbe two batches of push, the first asking the remote-helperto push the local ref master to the remote ref master andthe local HEAD to the remote branch, and the secondasking to push ref foo to ref bar (forced update requestedby the +).

push refs/heads/master:refs/heads/masterpush HEAD:refs/heads/branch\npush +refs/heads/foo:refs/heads/bar\n

Zero or more protocol options may be entered after the last pushcommand, before the batch’s terminating blank line.

When the push is complete, outputs one or more ok <dst> orerror <dst> <why>? lines to indicate success or failure ofeach pushed ref. The status report output is terminated bya blank line. The option field <why> may be quoted in a Cstyle string if it contains an LF.

Supported if the helper has the "push" capability.

Produces a fast-import stream which imports the current valueof the named ref. It may additionally import other refs asneeded to construct the history efficiently. The script writesto a helper-specific private namespace. The value of the namedref should be written to a location in this namespace derivedby applying the refspecs from the "refspec" capability to thename of the ref.

Especially useful for interoperability with a foreign versioningsystem.

Just like push, a batch sequence of one or more import isterminated with a blank line. For each batch of import, the remotehelper should produce a fast-import stream terminated by a donecommand.

Note that if the bidi-import capability is used the complete batchsequence has to be buffered before starting to send data to fast-importto prevent mixing of commands and fast-import responses on the helper’sstdin.

Supported if the helper has the "import" capability.

Instructs the remote helper that any subsequent input ispart of a fast-import stream (generated by git fast-export)containing objects which should be pushed to the remote.

Especially useful for interoperability with a foreign versioningsystem.

The export-marks and import-marks capabilities, if specified,affect this command in so far as they are passed on to gitfast-export, which then will load/store a table of marks forlocal objects. This can be used to implement for incrementaloperations.

Supported if the helper has the "export" capability.

Connects to given service. Standard input and standard outputof helper are connected to specified service (git prefix isincluded in service name so e.g. fetching uses git-upload-packas service) on remote side. Valid replies to this command areempty line (connection established), fallback (no smarttransport support, fall back to dumb transports) and justexiting with error message printed (can’t connect, don’tbother trying to fall back). After line feed terminating thepositive (empty) response, the output of service starts. Afterthe connection ends, the remote helper exits.

Supported if the helper has the "connect" capability.

Experimental; for internal use only.Connects to the given remote service for communication usinggit’s wire-protocol version 2. Valid replies to this commandare empty line (connection established), fallback (no smarttransport support, fall back to dumb transports) and justexiting with error message printed (can’t connect, don’t bothertrying to fall back). After line feed terminating the positive(empty) response, the output of the service starts. Messages(both request and response) must consist of zero or morePKT-LINEs, terminating in a flush packet. Response messages willthen have a response end packet after the flush packet toindicate the end of a response. The client must notexpect the server to store any state in between request-responsepairs. After the connection ends, the remote helper exits.

Supported if the helper has the "stateless-connect" capability.

Downloads the file from the given <uri> to the given <path>. If<path>.temp exists, then Git assumes that the .temp file is apartial download from a previous attempt and will resume thedownload from that position.