gitremote-helpers

Git invokes a remote helper program with the following syntax:
git-remote-
Where:
is the scheme from the remote URL (e.g., 'http', 'hg', 'fossil').
is the path to the current Git repository.
is the full remote repository URL.

capabilities
    Git asks the helper to list its supported features (e.g., fetch, push, option).

list
    Git requests a list of all references (branches, tags) and their corresponding object IDs from the remote repository.

option
    Git sets an option for the helper (e.g., option verbosity 2).

fetch
    Git asks the helper to fetch the object identified by , along with its history and objects. The helper responds with a packfile.

push :
    Git instructs the helper to push the local reference to the remote reference .

connect
    Git requests a connection to a specific remote service (e.g., 'git-upload-pack', 'git-receive-pack') for transport. This is primarily for native Git protocols.

setoption
    A newer command for setting general remote options.

refspec
    Used to configure fetch/push refspecs for the remote helper.

import-marks
    Instructs the helper to load marks from a file, primarily for fast-import like operations.

export-marks
    Instructs the helper to save marks to a file.

get-url
    Requests the helper to provide the canonical URL of the remote.

The gitremote-helpers mechanism defines a standardized protocol that allows Git to interact with remote repositories using arbitrary, external helper programs.
This extensibility enables Git to support various non-native protocols or repository types (e.g., Mercurial, Fossil, Subversion) without needing to embed their logic directly into the Git core.
When Git needs to communicate with a remote whose URL starts with a custom scheme (e.g., hg::, fossil::), it invokes a corresponding helper program named git-remote-.
The helper then communicates with Git via its standard input and output, exchanging commands (from Git to helper) and responses (from helper to Git).
This includes operations like listing references, fetching objects, and pushing changes.
The protocol ensures a clean separation of concerns, allowing third-party developers to extend Git's remote capabilities.

Implementing a robust remote helper can be complex due to the need to fully understand and correctly implement the Git packfile format and reference negotiation.
Performance can be an issue if the helper is inefficient or involves many external process invocations.
Security must be considered carefully, as a malicious or buggy helper could expose sensitive data or corrupt the local repository.
The protocol itself can evolve, requiring helpers to be updated to support new features or adhere to changes.

The interaction between Git and a remote helper occurs over standard input/output.
Git sends commands on lines terminated by a newline, and the helper responds similarly.
After processing a command, the helper typically prints ok to indicate success or error followed by a message.
The protocol supports capabilities negotiation, allowing Git and the helper to agree on supported features.
For fetching, helpers are expected to stream packfiles to Git's stdout.

Remote helper programs must be named git-remote- and reside in Git's executable search path (e.g., ~/bin or a directory listed in $PATH).
When Git encounters a URL like fossil::/path/to/repo.fossil, it attempts to execute git-remote-fossil.

The remote helper mechanism was introduced early in Git's development to provide a flexible way to interact with various network protocols and repository types beyond Git's native capabilities.
It allowed Git to integrate with other version control systems (like CVS, Subversion, Mercurial) through external bridges, thereby extending its reach and interoperability without bloating the core Git codebase.
This design philosophy emphasizes modularity and extensibility, which are hallmarks of Git's architecture.

git(1), git-remote(1), git-fetch(1), git-push(1), git-fast-import(1)