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.txt245
1 files changed, 0 insertions, 245 deletions
diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt
deleted file mode 100644
index 930b4034ac..0000000000
--- a/Documentation/git-remote-helpers.txt
+++ /dev/null
@@ -1,245 +0,0 @@
-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 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
---------
-
-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.
-+
-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.
-+
-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.
-
-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/{asterisk}:refs/svn/origin/branches/{asterisk}" 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 "{asterisk}:{asterisk}"
-
-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]
-
-GIT
----
-Part of the linkgit:git[1] suite