| 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. |
| |
| 'option pushcert {'true'|'false'}:: |
| GPG sign pushes. |
| |
| SEE ALSO |
| -------- |
| linkgit:git-remote[1] |
| |
| linkgit:git-remote-ext[1] |
| |
| linkgit:git-remote-fd[1] |
| |
| linkgit:git-remote-testgit[1] |
| |
| linkgit:git-fast-import[1] |
| |
| GIT |
| --- |
| Part of the linkgit:git[1] suite |