From: Junio C Hamano Date: Thu, 7 Feb 2013 22:41:45 +0000 (-0800) Subject: Merge branch 'jk/remote-helpers-doc' X-Git-Tag: v1.8.2-rc0~42 X-Git-Url: https://git.lorimer.id.au/gitweb.git/diff_plain/8e12ab2f336aea36dc29f4129926a69e6ba67027 Merge branch 'jk/remote-helpers-doc' "git help remote-helpers" did not work; 'remote-helpers' is not a subcommand name but a concept, so its documentation should have been in gitremote-helpers, not git-remote-helpers. * jk/remote-helpers-doc: Rename {git- => git}remote-helpers.txt --- 8e12ab2f336aea36dc29f4129926a69e6ba67027 diff --cc Documentation/gitremote-helpers.txt index 0000000000,0f21367ca5..0c91aba861 mode 000000,100644..100644 --- a/Documentation/gitremote-helpers.txt +++ b/Documentation/gitremote-helpers.txt @@@ -1,0 -1,423 +1,423 @@@ + gitremote-helpers(1) + ==================== + + NAME + ---- + gitremote-helpers - Helper programs to interact with remote repositories + + SYNOPSIS + -------- + [verse] + 'git remote-' [] + + 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 ++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. ++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 ++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; ++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 + '://
', 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. ++which directory to invoke auxiliary Git commands. + -When git encounters a URL of the form '://
', where ++When Git encounters a URL of the form '://
', where + '' is a protocol that it cannot handle natively, it + automatically invokes 'git remote-' 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 '::
' explicitly instructs git to ++A URL of the form '::
' explicitly instructs Git to + invoke 'git remote-' with '
' as the second + argument. If such a URL is encountered directly on the command line, + the first argument is '
', 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..vcs' set to -'', git explicitly invokes 'git remote-' with ++'', Git explicitly invokes 'git remote-' with + '' as the first argument. If set, the second argument is + 'remote..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 ++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 ++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'. ++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 ++ 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 ++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'. ++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' :: + 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 ++ 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 ++ 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' :: - This modifies the 'export' capability, instructing git to dump the ++ This modifies the 'export' capability, instructing Git to dump the + internal marks table to when complete. For details, + read up on '--export-marks=' in linkgit:git-fast-export[1]. + + 'import-marks' :: - This modifies the 'export' capability, instructing git to load the ++ This modifies the 'export' capability, instructing Git to load the + marks specified in before processing any input. For details, + read up on '--import-marks=' in linkgit:git-fast-export[1]. + + + + + 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 ++ 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 " + [ ...]". The value may be a hex sha1 hash, "@" 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' :: + Sets the transport helper option to . Outputs a + single line containing one of 'ok' (option successfully set), + 'unsupported' (option not recognized) or 'error ' + (option is supported but 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' :: + 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 ' 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' +::: + Pushes the given local commit or branch to the + remote branch described by . 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 ' or + 'error ?' lines to indicate success or failure of + each pushed ref. The status report output is terminated by + a blank line. The option field may be quoted in a C + style string if it contains an LF. + + + Supported if the helper has the "push" capability. + + 'import' :: + 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' :: + 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. ++set by Git if the remote helper has the 'option' capability. + + 'option verbosity' :: + Changes the verbosity of messages displayed by the helper. + A value of 0 for means that processes operate + quietly, and the helper produces only error output. + 1 is the default level of verbosity, and higher values + of 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' :: + 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 ':: + 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] + + linkgit:git-remote-testgit[1] + + GIT + --- + Part of the linkgit:git[1] suite