Merge git://git.bogomips.org/git-svn
[gitweb.git] / Documentation / git-remote-helpers.txt
index 8beb42dbb9952059650d51d2e7a5ca2efe9591fb..3a23477ce72763b562258a25c3777dd57ac1a962 100644 (file)
@@ -3,20 +3,69 @@ 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>
+'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 will
+use to determine what other commands the helper will accept.  Other
+commands generally concern facilities like discovering and updating
+remote refs, transporting objects between the object database and
+the remote repository, and updating the local object store.
+
+Helpers supporting the 'fetch' capability can discover refs from the
+remote repository and transfer objects reachable from those refs to
+the local object store. Helpers supporting the 'push' capability can
+transfer local objects to the remote repository and update remote refs.
+
+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'.
+
+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.
+
+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,34 +74,37 @@ 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.
+       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. 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.
@@ -64,7 +116,7 @@ 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.
 +
@@ -79,6 +131,34 @@ 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.
++
+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
@@ -91,13 +171,21 @@ CAPABILITIES
 ------------
 
 'fetch'::
-       This helper supports the 'fetch' command.
-
 'option'::
-       This helper supports the option command.
-
 'push'::
-       This helper supports the 'push' command.
+'import'::
+'connect'::
+       This helper supports the corresponding command with the same name.
+
+'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 "*:*"
 
 REF LIST ATTRIBUTES
 -------------------
@@ -107,22 +195,26 @@ REF LIST ATTRIBUTES
        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>::
-       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
+       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
@@ -137,9 +229,19 @@ OPTIONS
        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]
+
 Documentation
 -------------
-Documentation by Daniel Barkalow.
+Documentation by Daniel Barkalow and Ilari Liusvaara
 
 GIT
 ---