You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
369 lines
14 KiB
369 lines
14 KiB
git-remote-helpers(1) |
|
===================== |
|
|
|
NAME |
|
---- |
|
git-remote-helpers - Helper programs to interact with remote repositories |
|
|
|
SYNOPSIS |
|
-------- |
|
[verse] |
|
'git remote-<transport>' <repository> [<URL>] |
|
|
|
DESCRIPTION |
|
----------- |
|
|
|
Remote helper programs are normally not used directly by end users, |
|
but they are invoked by git when it needs to interact with remote |
|
repositories git does not support natively. A given helper will |
|
implement a subset of the capabilities documented here. When git |
|
needs to interact with a repository using a remote helper, it spawns |
|
the helper as an independent process, sends commands to the helper's |
|
standard input, and expects results from the helper's standard |
|
output. Because a remote helper runs as an independent process from |
|
git, there is no need to re-link git to add a new helper, nor any |
|
need to link the helper with the implementation of git. |
|
|
|
Every helper must support the "capabilities" command, which git |
|
uses to determine what other commands the helper will accept. Those |
|
other commands can be used to discover and update remote refs, |
|
transport objects between the object database and the remote repository, |
|
and update the local object store. |
|
|
|
Git comes with a "curl" family of remote helpers, that handle various |
|
transport protocols, such as 'git-remote-http', 'git-remote-https', |
|
'git-remote-ftp' and 'git-remote-ftps'. They implement the capabilities |
|
'fetch', 'option', and 'push'. |
|
|
|
INPUT FORMAT |
|
------------ |
|
|
|
Git sends the remote helper a list of commands on standard input, one |
|
per line. The first command is always the 'capabilities' command, in |
|
response to which the remote helper must print a list of the |
|
capabilities it supports (see below) followed by a blank line. The |
|
response to the capabilities command determines what commands Git uses |
|
in the remainder of the command stream. |
|
|
|
The command stream is terminated by a blank line. In some cases |
|
(indicated in the documentation of the relevant commands), this blank |
|
line is followed by a payload in some other protocol (e.g., the pack |
|
protocol), while in others it indicates the end of input. |
|
|
|
Capabilities |
|
~~~~~~~~~~~~ |
|
|
|
Each remote helper is expected to support only a subset of commands. |
|
The operations a helper supports are declared to git in the response |
|
to the `capabilities` command (see COMMANDS, below). |
|
|
|
'option':: |
|
For specifying settings like `verbosity` (how much output to |
|
write to stderr) and `depth` (how much history is wanted in the |
|
case of a shallow clone) that affect how other commands are |
|
carried out. |
|
|
|
'connect':: |
|
For fetching and pushing using git's native packfile protocol |
|
that requires a bidirectional, full-duplex connection. |
|
|
|
'push':: |
|
For listing remote refs and pushing specified objects from the |
|
local object store to remote refs. |
|
|
|
'fetch':: |
|
For listing remote refs and fetching the associated history to |
|
the local object store. |
|
|
|
'import':: |
|
For listing remote refs and fetching the associated history as |
|
a fast-import stream. |
|
|
|
'refspec' <refspec>:: |
|
This modifies the 'import' capability, allowing the produced |
|
fast-import stream to modify refs in a private namespace |
|
instead of writing to refs/heads or refs/remotes directly. |
|
It is recommended that all importers providing the 'import' |
|
capability use this. |
|
+ |
|
A helper advertising the capability |
|
`refspec refs/heads/*:refs/svn/origin/branches/*` |
|
is saying that, when it is asked to `import refs/heads/topic`, the |
|
stream it outputs will update the `refs/svn/origin/branches/topic` |
|
ref. |
|
+ |
|
This capability can be advertised multiple times. The first |
|
applicable refspec takes precedence. The left-hand of refspecs |
|
advertised with this capability must cover all refs reported by |
|
the list command. If no 'refspec' capability is advertised, |
|
there is an implied `refspec *:*`. |
|
|
|
Capabilities for Pushing |
|
~~~~~~~~~~~~~~~~~~~~~~~~ |
|
'connect':: |
|
Can attempt to connect to 'git receive-pack' (for pushing), |
|
'git upload-pack', etc for communication using the |
|
packfile protocol. |
|
+ |
|
Supported commands: 'connect'. |
|
|
|
'push':: |
|
Can discover remote refs and push local commits and the |
|
history leading up to them to new or existing remote refs. |
|
+ |
|
Supported commands: 'list for-push', 'push'. |
|
|
|
If a helper advertises both 'connect' and 'push', git will use |
|
'connect' if possible and fall back to 'push' if the helper requests |
|
so when connecting (see the 'connect' command under COMMANDS). |
|
|
|
Capabilities for Fetching |
|
~~~~~~~~~~~~~~~~~~~~~~~~~ |
|
'connect':: |
|
Can try to connect to 'git upload-pack' (for fetching), |
|
'git receive-pack', etc for communication using the |
|
packfile protocol. |
|
+ |
|
Supported commands: 'connect'. |
|
|
|
'fetch':: |
|
Can discover remote refs and transfer objects reachable from |
|
them to the local object store. |
|
+ |
|
Supported commands: 'list', 'fetch'. |
|
|
|
'import':: |
|
Can discover remote refs and output objects reachable from |
|
them as a stream in fast-import format. |
|
+ |
|
Supported commands: 'list', 'import'. |
|
|
|
If a helper advertises 'connect', git will use it if possible and |
|
fall back to another capability if the helper requests so when |
|
connecting (see the 'connect' command under COMMANDS). |
|
When choosing between 'fetch' and 'import', git prefers 'fetch'. |
|
Other frontends may have some other order of preference. |
|
|
|
'refspec' <refspec>:: |
|
This modifies the 'import' capability. |
|
+ |
|
A helper advertising |
|
`refspec refs/heads/*:refs/svn/origin/branches/*` |
|
in its capabilities is saying that, when it handles |
|
`import refs/heads/topic`, the stream it outputs will update the |
|
`refs/svn/origin/branches/topic` ref. |
|
+ |
|
This capability can be advertised multiple times. The first |
|
applicable refspec takes precedence. The left-hand of refspecs |
|
advertised with this capability must cover all refs reported by |
|
the list command. If no 'refspec' capability is advertised, |
|
there is an implied `refspec *:*`. |
|
|
|
INVOCATION |
|
---------- |
|
|
|
Remote helper programs are invoked with one or (optionally) two |
|
arguments. The first argument specifies a remote repository as in git; |
|
it is either the name of a configured remote or a URL. The second |
|
argument specifies a URL; it is usually of the form |
|
'<transport>://<address>', but any arbitrary string is possible. |
|
The 'GIT_DIR' environment variable is set up for the remote helper |
|
and can be used to determine where to store additional data or from |
|
which directory to invoke auxiliary git commands. |
|
|
|
When git encounters a URL of the form '<transport>://<address>', where |
|
'<transport>' is a protocol that it cannot handle natively, it |
|
automatically invokes 'git remote-<transport>' with the full URL as |
|
the second argument. If such a URL is encountered directly on the |
|
command line, the first argument is the same as the second, and if it |
|
is encountered in a configured remote, the first argument is the name |
|
of that remote. |
|
|
|
A URL of the form '<transport>::<address>' explicitly instructs git to |
|
invoke 'git remote-<transport>' with '<address>' as the second |
|
argument. If such a URL is encountered directly on the command line, |
|
the first argument is '<address>', and if it is encountered in a |
|
configured remote, the first argument is the name of that remote. |
|
|
|
Additionally, when a configured remote has 'remote.<name>.vcs' set to |
|
'<transport>', git explicitly invokes 'git remote-<transport>' with |
|
'<name>' as the first argument. If set, the second argument is |
|
'remote.<name>.url'; otherwise, the second argument is omitted. |
|
|
|
COMMANDS |
|
-------- |
|
|
|
Commands are given by the caller on the helper's standard input, one per line. |
|
|
|
'capabilities':: |
|
Lists the capabilities of the helper, one per line, ending |
|
with a blank line. Each capability may be preceded with '*', |
|
which marks them mandatory for git version using the remote |
|
helper to understand (unknown mandatory capability is fatal |
|
error). |
|
|
|
'list':: |
|
Lists the refs, one per line, in the format "<value> <name> |
|
[<attr> ...]". The value may be a hex sha1 hash, "@<dest>" for |
|
a symref, or "?" to indicate that the helper could not get the |
|
value of the ref. A space-separated list of attributes follows |
|
the name; unrecognized attributes are ignored. The list ends |
|
with a blank line. |
|
+ |
|
If 'push' is supported this may be called as 'list for-push' |
|
to obtain the current refs prior to sending one or more 'push' |
|
commands to the helper. |
|
|
|
'option' <name> <value>:: |
|
Sets the transport helper option <name> to <value>. Outputs a |
|
single line containing one of 'ok' (option successfully set), |
|
'unsupported' (option not recognized) or 'error <msg>' |
|
(option <name> is supported but <value> is not valid |
|
for it). Options should be set before other commands, |
|
and may influence the behavior of those commands. |
|
+ |
|
Supported if the helper has the "option" capability. |
|
|
|
'fetch' <sha1> <name>:: |
|
Fetches the given object, writing the necessary objects |
|
to the database. Fetch commands are sent in a batch, one |
|
per line, terminated with a blank line. |
|
Outputs a single blank line when all fetch commands in the |
|
same batch are complete. Only objects which were reported |
|
in the ref list with a sha1 may be fetched this way. |
|
+ |
|
Optionally may output a 'lock <file>' line indicating a file under |
|
GIT_DIR/objects/pack which is keeping a pack until refs can be |
|
suitably updated. |
|
+ |
|
Supported if the helper has the "fetch" capability. |
|
|
|
'push' +<src>:<dst>:: |
|
Pushes the given local <src> commit or branch to the |
|
remote branch described by <dst>. A batch sequence of |
|
one or more 'push' commands is terminated with a blank line |
|
(if there is only one reference to push, a single 'push' command |
|
is followed by a blank line). For example, the following would |
|
be two batches of 'push', the first asking the remote-helper |
|
to push the local ref 'master' to the remote ref 'master' and |
|
the local 'HEAD' to the remote 'branch', and the second |
|
asking to push ref 'foo' to ref 'bar' (forced update requested |
|
by the '+'). |
|
+ |
|
------------ |
|
push refs/heads/master:refs/heads/master |
|
push HEAD:refs/heads/branch |
|
\n |
|
push +refs/heads/foo:refs/heads/bar |
|
\n |
|
------------ |
|
+ |
|
Zero or more protocol options may be entered after the last 'push' |
|
command, before the batch's terminating blank line. |
|
+ |
|
When the push is complete, outputs one or more 'ok <dst>' or |
|
'error <dst> <why>?' lines to indicate success or failure of |
|
each pushed ref. The status report output is terminated by |
|
a blank line. The option field <why> may be quoted in a C |
|
style string if it contains an LF. |
|
+ |
|
Supported if the helper has the "push" capability. |
|
|
|
'import' <name>:: |
|
Produces a fast-import stream which imports the current value |
|
of the named ref. It may additionally import other refs as |
|
needed to construct the history efficiently. The script writes |
|
to a helper-specific private namespace. The value of the named |
|
ref should be written to a location in this namespace derived |
|
by applying the refspecs from the "refspec" capability to the |
|
name of the ref. |
|
+ |
|
Especially useful for interoperability with a foreign versioning |
|
system. |
|
+ |
|
Just like 'push', a batch sequence of one or more 'import' is |
|
terminated with a blank line. For each batch of 'import', the remote |
|
helper should produce a fast-import stream terminated by a 'done' |
|
command. |
|
+ |
|
Supported if the helper has the "import" capability. |
|
|
|
'connect' <service>:: |
|
Connects to given service. Standard input and standard output |
|
of helper are connected to specified service (git prefix is |
|
included in service name so e.g. fetching uses 'git-upload-pack' |
|
as service) on remote side. Valid replies to this command are |
|
empty line (connection established), 'fallback' (no smart |
|
transport support, fall back to dumb transports) and just |
|
exiting with error message printed (can't connect, don't |
|
bother trying to fall back). After line feed terminating the |
|
positive (empty) response, the output of service starts. After |
|
the connection ends, the remote helper exits. |
|
+ |
|
Supported if the helper has the "connect" capability. |
|
|
|
If a fatal error occurs, the program writes the error message to |
|
stderr and exits. The caller should expect that a suitable error |
|
message has been printed if the child closes the connection without |
|
completing a valid response for the current command. |
|
|
|
Additional commands may be supported, as may be determined from |
|
capabilities reported by the helper. |
|
|
|
REF LIST ATTRIBUTES |
|
------------------- |
|
|
|
'for-push':: |
|
The caller wants to use the ref list to prepare push |
|
commands. A helper might chose to acquire the ref list by |
|
opening a different type of connection to the destination. |
|
|
|
'unchanged':: |
|
This ref is unchanged since the last import or fetch, although |
|
the helper cannot necessarily determine what value that produced. |
|
|
|
OPTIONS |
|
------- |
|
'option verbosity' <n>:: |
|
Changes the verbosity of messages displayed by the helper. |
|
A value of 0 for <n> means that processes operate |
|
quietly, and the helper produces only error output. |
|
1 is the default level of verbosity, and higher values |
|
of <n> correspond to the number of -v flags passed on the |
|
command line. |
|
|
|
'option progress' \{'true'|'false'\}:: |
|
Enables (or disables) progress messages displayed by the |
|
transport helper during a command. |
|
|
|
'option depth' <depth>:: |
|
Deepens the history of a shallow repository. |
|
|
|
'option followtags' \{'true'|'false'\}:: |
|
If enabled the helper should automatically fetch annotated |
|
tag objects if the object the tag points at was transferred |
|
during the fetch command. If the tag is not fetched by |
|
the helper a second fetch command will usually be sent to |
|
ask for the tag specifically. Some helpers may be able to |
|
use this option to avoid a second network connection. |
|
|
|
'option dry-run' \{'true'|'false'\}: |
|
If true, pretend the operation completed successfully, |
|
but don't actually change any repository data. For most |
|
helpers this only applies to the 'push', if supported. |
|
|
|
'option servpath <c-style-quoted-path>':: |
|
Sets service path (--upload-pack, --receive-pack etc.) for |
|
next connect. Remote helper may support this option, but |
|
must not rely on this option being set before |
|
connect request occurs. |
|
|
|
SEE ALSO |
|
-------- |
|
linkgit:git-remote[1] |
|
|
|
linkgit:git-remote-testgit[1] |
|
|
|
GIT |
|
--- |
|
Part of the linkgit:git[1] suite
|
|
|