summaryrefslogtreecommitdiff
path: root/Documentation/git-remote-helpers.txt
diff options
context:
space:
mode:
Diffstat (limited to 'Documentation/git-remote-helpers.txt')
-rw-r--r--Documentation/git-remote-helpers.txt287
1 files changed, 228 insertions, 59 deletions
diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt
index 4685a898f1..674797cd83 100644
--- a/Documentation/git-remote-helpers.txt
+++ b/Documentation/git-remote-helpers.txt
@@ -3,20 +3,192 @@ git-remote-helpers(1)
NAME
----
-git-remote-helpers - Helper programs for interoperation with remote git
+git-remote-helpers - Helper programs to interact with remote repositories
SYNOPSIS
--------
-'git remote-<transport>' <remote>
+[verse]
+'git remote-<transport>' <repository> [<URL>]
DESCRIPTION
-----------
-These programs are normally not used directly by end users, but are
-invoked by various git programs that interact with remote repositories
-when the repository they would operate on will be accessed using
-transport code not linked into the main git binary. Various particular
-helper programs will behave as documented here.
+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/{asterisk}:refs/svn/origin/branches/{asterisk}`
+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 {asterisk}:{asterisk}`.
+
+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/{asterisk}:refs/svn/origin/branches/{asterisk}`
+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 {asterisk}:{asterisk}`.
+
+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
--------
@@ -25,8 +197,8 @@ 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 preceeded with '*'.
- This marks them mandatory for git version using the remote
+ 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).
@@ -35,27 +207,27 @@ Commands are given by the caller on the helper's standard input, one per line.
[<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. After the
- complete list, outputs a blank line.
+ 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>::
- Set the transport helper option <name> to <value>. Outputs a
+ 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 correct
+ (option <name> is supported but <value> is not valid
for it). Options should be set before other commands,
- and may how those commands behave.
+ 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, and the batch is terminated with a blank line.
+ 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.
@@ -67,9 +239,24 @@ suitably updated.
Supported if the helper has the "fetch" capability.
'push' +<src>:<dst>::
- Pushes the given <src> commit or branch locally to the
+ 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.
+ 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.
@@ -91,6 +278,14 @@ Supported if the helper has the "push" capability.
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>::
@@ -115,34 +310,6 @@ completing a valid response for the current command.
Additional commands may be supported, as may be determined from
capabilities reported by the helper.
-CAPABILITIES
-------------
-
-'fetch'::
- This helper supports the 'fetch' command.
-
-'option'::
- This helper supports the option command.
-
-'push'::
- This helper supports the 'push' command.
-
-'import'::
- This helper supports the 'import' command.
-
-'refspec' 'spec'::
- When using the import command, expect the source ref to have
- been written to the destination ref. The earliest applicable
- refspec takes precedence. For example
- "refs/heads/*:refs/svn/origin/branches/*" means that, after an
- "import refs/heads/name", the script has written to
- refs/svn/origin/branches/name. If this capability is used at
- all, it must cover all refs reported by the list command; if
- it is not used, it is effectively "*:*"
-
-'connect'::
- This helper supports the 'connect' command.
-
REF LIST ATTRIBUTES
-------------------
@@ -157,20 +324,20 @@ REF LIST ATTRIBUTES
OPTIONS
-------
-'option verbosity' <N>::
- Change the level of messages displayed by the helper.
- When N is 0 the end-user has asked the process to be
- quiet, and the helper should produce only error output.
- N of 1 is the default level of verbosity, higher values
- of N correspond to the number of -v flags passed on the
+'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'\}::
- Enable (or disable) progress messages displayed by the
+ Enables (or disables) progress messages displayed by the
transport helper during a command.
'option depth' <depth>::
- Deepen the history of a shallow repository.
+ Deepens the history of a shallow repository.
'option followtags' \{'true'|'false'\}::
If enabled the helper should automatically fetch annotated
@@ -186,14 +353,16 @@ OPTIONS
helpers this only applies to the 'push', if supported.
'option servpath <c-style-quoted-path>'::
- Set service path (--upload-pack, --receive-pack etc.) for
- next connect. Remote helper MAY support this option. Remote
- helper MUST NOT rely on this option being set before
+ 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.
-Documentation
--------------
-Documentation by Daniel Barkalow and Ilari Liusvaara
+SEE ALSO
+--------
+linkgit:git-remote[1]
+
+linkgit:git-remote-testgit[1]
GIT
---