Git Reference ยท Remotes and Collaboration
Remote helpers (git-remote-*)
Reference for Git remote helpers: how git-remote-<name> programs add URL schemes, the transport:: syntax, the capabilities handshake, and a minimal working helper.
A remote helper is an external program that teaches Git to talk to a kind of remote it does not know about. When a URL starts with <name>:: or has a scheme <name>:// that Git does not handle itself, Git runs a program called git-remote-<name> and speaks a line-based protocol with it on standard input and output.
The built-in transports for https, http, ftp and ftps are themselves helpers (git-remote-http and friends, built with libcurl). Third-party helpers add cloud storage, other version-control systems (Mercurial, Subversion, Bazaar), encrypted remotes and more.
git clone <name>::<address> [dir] git remote add origin <name>::<address> # Git runs: git-remote-<name> <remote-name-or-url> <url>
Try it
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Press Run (or Ctrl + Enter) to see the result here.
Program input ยท what you'd type while the program runs
Type the answers before you press Run, one per line. Each time the program reads a line (with read or cat), it gets the next line from this box.
Syntax
Invocation: git-remote-<name> <remote> [<url>]. The first argument is the remote's name (or the URL if none exists), the second is the URL without the name:: prefix. The program must be in PATH or in Git's exec path (git --exec-path).
Protocol: Git writes a command on one line; the helper answers and ends a reply with an empty line.
| Command from Git | Meaning and expected reply |
|---|---|
capabilities |
The helper lists what it supports, one per line, ending with a blank line. |
list [for-push] |
Print <value> <name> [<attrs>] lines for each remote ref (the value is an object ID, ?, or @<symref>), then a blank line. |
fetch <sha1> <name> |
Download objects, then a blank line. Sent in batches. |
push <src>:<dst> |
Upload; reply ok <dst> or error <dst> <why> per ref, then a blank line. |
connect <service> |
Only with the connect capability: reply with an empty line, then act as git-upload-pack or git-receive-pack, speaking the pack protocol on the same pipes. |
import, export |
Exchange history as a fast-import stream (used by helpers for foreign systems). |
option <name> <value> |
Pass options such as verbosity or depth; reply ok, unsupported or error. |
Common capabilities: fetch, push, import, export, connect, stateless-connect, refspec <spec>, option, check-connectivity, get, gitdir, signed-tags, object-format. Prefix * marks a capability as mandatory.
Usage notes
transport::addressform. Everything after::goes to the helper unchanged, even if it looks like another URL. This is howgit clone hg::https://example.com/reporeachesgit-remote-hg.- Direct scheme. A URL of the form
name://...also runsgit-remote-namewhen Git does not know the scheme.url.<base>.insteadOfrewrites can hide a longname::prefix, see URL rewriting. - Errors go to stderr. Standard error is shown to the user. Standard output is the protocol, so a stray
echobreaks everything. connectis the easy way to wrap a custom transport (a tunnel, a proxy, a container exec): after the handshake, bytes flow as with SSH.stateless-connectdoes the same for protocol v2 over request/response transports such as HTTP.- Security. A helper runs with your privileges, and Git runs it automatically for a matching URL. Restrict which protocols are allowed with
protocol.allowandGIT_ALLOW_PROTOCOL. See protocol.* settings. - Debugging. Set
GIT_TRACE=1andGIT_TRACE_PACKET=1to see the exchange, or print traffic to stderr as in the second example. - Performance. For large histories, helpers that use
import/exportare slower thanfetch/pushwith real packs, because they translate every object.