gitremote-helpers
Access Git repositories using helper programs
SYNOPSIS
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.
PARAMETERS
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.
DESCRIPTION
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.
CAVEATS
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.
PROTOCOL DETAILS
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.
HELPER NAMING CONVENTION
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
.
HISTORY
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.
SEE ALSO
git(1), git-remote(1), git-fetch(1), git-push(1), git-fast-import(1)