Skip to content
Tutorials Center
My learning

Topics

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.

Terminal
git clone <name>::<address> [dir]
git remote add origin <name>::<address>
# Git runs:  git-remote-<name> <remote-name-or-url> <url>

Try it

Bash A minimal helper that forwards to upload-pack

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.

Bash What the handshake looks like

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::address form. Everything after :: goes to the helper unchanged, even if it looks like another URL. This is how git clone hg::https://example.com/repo reaches git-remote-hg.
  • Direct scheme. A URL of the form name://... also runs git-remote-name when Git does not know the scheme. url.<base>.insteadOf rewrites can hide a long name:: prefix, see URL rewriting.
  • Errors go to stderr. Standard error is shown to the user. Standard output is the protocol, so a stray echo breaks everything.
  • connect is the easy way to wrap a custom transport (a tunnel, a proxy, a container exec): after the handshake, bytes flow as with SSH. stateless-connect does 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.allow and GIT_ALLOW_PROTOCOL. See protocol.* settings.
  • Debugging. Set GIT_TRACE=1 and GIT_TRACE_PACKET=1 to see the exchange, or print traffic to stderr as in the second example.
  • Performance. For large histories, helpers that use import/export are slower than fetch/push with real packs, because they translate every object.