SYNOPSIS
--------
+[verse]
'git remote-<transport>' <repository> [<URL>]
DESCRIPTION
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.
+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',
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
'<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.
+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'.
+
+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 '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
+ 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'.
+
+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.
+
+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.
+ If it is advertised in addition to "import", git establishes a pipe from
+ fast-import to the remote-helper's stdin.
+ 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 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>::
+ 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
--------
'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).
+ 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>
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.
+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
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>::
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.
+ 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
'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.
+ 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.
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
Additional commands may be supported, as may be determined from
capabilities reported by the helper.
-CAPABILITIES
-------------
-
-'fetch'::
-'option'::
-'push'::
-'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
-------------------
-'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.
+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
OPTIONS
-------
-'option verbosity' <N>::
+
+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
+ 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
+ of <n> correspond to the number of -v flags passed on the
command line.
'option progress' \{'true'|'false'\}::
--------
linkgit:git-remote[1]
-Documentation
--------------
-Documentation by Daniel Barkalow and Ilari Liusvaara
+linkgit:git-remote-testgit[1]
GIT
---