diff options
Diffstat (limited to 'Documentation/gitremote-helpers.txt')
| -rw-r--r-- | Documentation/gitremote-helpers.txt | 459 |
1 files changed, 459 insertions, 0 deletions
diff --git a/Documentation/gitremote-helpers.txt b/Documentation/gitremote-helpers.txt new file mode 100644 index 0000000000..64f7ad26b4 --- /dev/null +++ b/Documentation/gitremote-helpers.txt @@ -0,0 +1,459 @@ +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, +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 +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 +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 +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 +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. + +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. + +'no-private-update':: + When using the 'refspec' capability, git normally updates the + private ref on successful push. This update is disabled when + the remote-helper declares the capability 'no-private-update'. + + +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'. + +'check-connectivity':: + Can guarantee that when a clone is requested, the received + pack is self contained and is connected. + +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>:: + For remote helpers that implement 'import' or 'export', this capability + allows the refs to be constrained to 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. It's mandatory for 'export'. ++ +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 *:*`. ++ +When writing remote-helpers for decentralized version control +systems, it is advised to keep a local copy of the repository to +interact with, and to let the private namespace refs point to this +local repository, while the refs/remotes namespace is used to track +the remote repository. + +'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]. + +'signed-tags':: + This modifies the 'export' capability, instructing Git to pass + '--signed-tags=verbatim' to linkgit:git-fast-export[1]. In the + absence of this capability, Git will use '--signed-tags=warn-strip'. + + + +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 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. ++ +If option 'check-connectivity' is requested, the helper must output +'connectivity-ok' if the clone is self-contained and connected. ++ +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. + +'option check-connectivity' \{'true'|'false'\}:: + Request the helper to check connectivity of a clone. + +'option force' \{'true'|'false'\}:: + Request the helper to perform a force update. Defaults to + 'false'. + +'option cloning \{'true'|'false'\}:: + Notify the helper this is a clone request (i.e. the current + repository is guaranteed empty). + +'option update-shallow \{'true'|'false'\}:: + Allow to extend .git/shallow if the new refs require it. + +SEE ALSO +-------- +linkgit:git-remote[1] + +linkgit:git-remote-testgit[1] + +GIT +--- +Part of the linkgit:git[1] suite |