diff options
Diffstat (limited to 'Documentation/git-remote-helpers.txt')
| -rw-r--r-- | Documentation/git-remote-helpers.txt | 248 |
1 files changed, 0 insertions, 248 deletions
diff --git a/Documentation/git-remote-helpers.txt b/Documentation/git-remote-helpers.txt deleted file mode 100644 index 3a23477ce7..0000000000 --- a/Documentation/git-remote-helpers.txt +++ /dev/null @@ -1,248 +0,0 @@ -git-remote-helpers(1) -===================== - -NAME ----- -git-remote-helpers - Helper programs to interact with remote repositories - -SYNOPSIS --------- -'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/*: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. - -'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] - -Documentation -------------- -Documentation by Daniel Barkalow and Ilari Liusvaara - -GIT ---- -Part of the linkgit:git[1] suite |