--- /dev/null
-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
+ gitremote-helpers(1)
+ ====================
+
+ NAME
+ ----
+ gitremote-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,
-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.
++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
-Every helper must support the "capabilities" command, which git
++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.
+
-arguments. The first argument specifies a remote repository as in 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'.
+
+ INVOCATION
+ ----------
+
+ Remote helper programs are invoked with one or (optionally) two
-which directory to invoke auxiliary git commands.
++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
-When git encounters a URL of the form '<transport>://<address>', where
++which directory to invoke auxiliary Git commands.
+
-A URL of the form '<transport>::<address>' explicitly instructs git to
++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.
+
-'<transport>', git explicitly invokes 'git remote-<transport>' with
++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
-The operations a helper supports are declared to git in the response
++'<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.
+
+ 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.
-If a helper advertises 'connect', git will use it if possible and
++The operations a helper supports are declared to Git in the response
+ to the `capabilities` command (see COMMANDS, below).
+
+ In the following, we list all defined capabilities and for
+ each we list which commands a helper with that capability
+ must provide.
+
+ Capabilities for Pushing
+ ^^^^^^^^^^^^^^^^^^^^^^^^
+ 'connect'::
+ Can attempt to connect to 'git receive-pack' (for pushing),
+ 'git upload-pack', etc for communication using
+ git's native packfile protocol. This
+ requires a bidirectional, full-duplex connection.
+ +
+ 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'.
+
+ 'export'::
+ Can discover remote refs and push specified objects from a
+ fast-import stream to remote refs.
+ +
+ Supported commands: 'list for-push', 'export'.
+
-When choosing between 'push' and 'export', git prefers 'push'.
++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).
- git's native packfile protocol. This
++When choosing between 'push' and 'export', Git prefers 'push'.
+ Other frontends may have some other order of preference.
+
+
+ Capabilities for Fetching
+ ^^^^^^^^^^^^^^^^^^^^^^^^^
+ 'connect'::
+ Can try to connect to 'git upload-pack' (for fetching),
+ 'git receive-pack', etc for communication using the
-If a helper advertises 'connect', git will use it if possible and
++ Git's native packfile protocol. This
+ requires a bidirectional, full-duplex connection.
+ +
+ 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'.
+
-When choosing between 'fetch' and 'import', git prefers 'fetch'.
++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).
- If it is advertised in addition to "import", git establishes a pipe from
++When choosing between 'fetch' and 'import', Git prefers 'fetch'.
+ Other frontends may have some other order of preference.
+
+ Miscellaneous capabilities
+ ^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+ '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.
+
+ '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 *:*`.
+
+ 'bidi-import'::
+ This modifies the 'import' capability.
+ The fast-import commands 'cat-blob' and 'ls' can be used by remote-helpers
+ to retrieve information about blobs and trees that already exist in
+ fast-import's memory. This requires a channel from fast-import to the
+ remote-helper.
- It follows that git and fast-import are both connected to the
- remote-helper's stdin. Because git can send multiple commands to
++ If it is advertised in addition to "import", Git establishes a pipe from
+ fast-import to the remote-helper's stdin.
- This modifies the 'export' capability, instructing git to dump the
++ It follows that Git and fast-import are both connected to the
++ remote-helper's stdin. Because Git can send multiple commands to
+ the remote-helper it is required that helpers that use 'bidi-import'
+ buffer all 'import' commands of a batch before sending data to fast-import.
+ This is to prevent mixing commands and fast-import responses on the
+ helper's stdin.
+
+ 'export-marks' <file>::
- This modifies the 'export' capability, instructing git to load the
++ This modifies the 'export' capability, instructing Git to dump the
+ internal marks table to <file> when complete. For details,
+ read up on '--export-marks=<file>' in linkgit:git-fast-export[1].
+
+ 'import-marks' <file>::
- which marks them mandatory for git versions using the remote
++ This modifies the 'export' capability, instructing Git to load the
+ marks specified in <file> before processing any input. For details,
+ read up on '--import-marks=<file>' in linkgit:git-fast-export[1].
+
+
+
+
+ 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 '*',
-set by git if the remote helper has the 'option' capability.
++ which marks them mandatory for Git versions using the remote
+ helper to understand. Any unknown mandatory capability is a
+ fatal error.
+ +
+ Support for this command is mandatory.
+
+ '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.
+ +
+ See REF LIST ATTRIBUTES for a list of currently defined attributes.
+ +
+ Supported if the helper has the "fetch" or "import" capability.
+
+ 'list for-push'::
+ Similar to 'list', except that it is used if and only if
+ the caller wants to the resulting ref list to prepare
+ push commands.
+ A helper supporting both push and fetch can use this
+ to distinguish for which operation the output of 'list'
+ is going to be used, possibly reducing the amount
+ of work that needs to be performed.
+ +
+ Supported if the helper has the "push" or "export" capability.
+
+ '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.
+ +
+ See OPTIONS for a list of currently defined options.
+ +
+ 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 output of '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.
+ +
+ Note that if the 'bidi-import' capability is used the complete batch
+ sequence has to be buffered before starting to send data to fast-import
+ to prevent mixing of commands and fast-import responses on the helper's
+ stdin.
+ +
+ Supported if the helper has the "import" capability.
+
+ 'export'::
+ Instructs the remote helper that any subsequent input is
+ part of a fast-import stream (generated by 'git fast-export')
+ containing objects which should be pushed to the remote.
+ +
+ Especially useful for interoperability with a foreign versioning
+ system.
+ +
+ The 'export-marks' and 'import-marks' capabilities, if specified,
+ affect this command in so far as they are passed on to 'git
+ fast-export', which then will load/store a table of marks for
+ local objects. This can be used to implement for incremental
+ operations.
+ +
+ Supported if the helper has the "export" 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
+ -------------------
+
+ The 'list' command produces a list of refs in which each ref
+ may be followed by a list of attributes. The following ref list
+ attributes are defined.
+
+ 'unchanged'::
+ This ref is unchanged since the last import or fetch, although
+ the helper cannot necessarily determine what value that produced.
+
+ OPTIONS
+ -------
+
+ The following options are defined and (under suitable circumstances)
++set by Git if the remote helper has the 'option' capability.
+
+ '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