diff options
| author | Junio C Hamano <gitster@pobox.com> | 2013-02-07 16:02:52 -0800 |
|---|---|---|
| committer | Junio C Hamano <gitster@pobox.com> | 2013-02-07 16:02:52 -0800 |
| commit | b5e079ffbacd06dc0749ca8040279d47f3c35423 (patch) | |
| tree | 2cef9e00ff8d4fb995fff56bc8fe6f09e4d8dae5 /git-remote-helpers.html | |
| parent | 076ffcc834f02a4f11d7f4fe8825be3b065020ff (diff) | |
| download | git-htmldocs-b5e079ffbacd06dc0749ca8040279d47f3c35423.tar.gz | |
Autogenerated HTML docs for v1.8.1.3-535-ga923c
Diffstat (limited to 'git-remote-helpers.html')
| -rw-r--r-- | git-remote-helpers.html | 550 |
1 files changed, 9 insertions, 541 deletions
diff --git a/git-remote-helpers.html b/git-remote-helpers.html index 0bbb08c44..cdd4e58f6 100644 --- a/git-remote-helpers.html +++ b/git-remote-helpers.html @@ -4,7 +4,7 @@ <head>
<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
<meta name="generator" content="AsciiDoc 8.6.8" />
-<title>git-remote-helpers(1)</title>
+<title>git-remote-helpers</title>
<style type="text/css">
/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
@@ -729,556 +729,24 @@ asciidoc.install(); /*]]>*/
</script>
</head>
-<body class="manpage">
+<body class="article">
<div id="header">
-<h1>
-git-remote-helpers(1) Manual Page
-</h1>
-<h2>NAME</h2>
-<div class="sectionbody">
-<p>git-remote-helpers -
- Helper programs to interact with remote repositories
-</p>
-</div>
+<h1>git-remote-helpers</h1>
</div>
<div id="content">
-<div class="sect1">
-<h2 id="_synopsis">SYNOPSIS</h2>
-<div class="sectionbody">
-<div class="verseblock">
-<pre class="content"><em>git remote-<transport></em> <repository> [<URL>]</pre>
-<div class="attribution">
-</div></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_description">DESCRIPTION</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>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.</p></div>
-<div class="paragraph"><p>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.</p></div>
-<div class="paragraph"><p>Git comes with a "curl" family of remote helpers, that handle various
-transport protocols, such as <em>git-remote-http</em>, <em>git-remote-https</em>,
-<em>git-remote-ftp</em> and <em>git-remote-ftps</em>. They implement the capabilities
-<em>fetch</em>, <em>option</em>, and <em>push</em>.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_invocation">INVOCATION</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>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
-<em><transport>://<address></em>, but any arbitrary string is possible.
-The <em>GIT_DIR</em> 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.</p></div>
-<div class="paragraph"><p>When Git encounters a URL of the form <em><transport>://<address></em>, where
-<em><transport></em> is a protocol that it cannot handle natively, it
-automatically invokes <em>git remote-<transport></em> 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.</p></div>
-<div class="paragraph"><p>A URL of the form <em><transport>::<address></em> explicitly instructs Git to
-invoke <em>git remote-<transport></em> with <em><address></em> as the second
-argument. If such a URL is encountered directly on the command line,
-the first argument is <em><address></em>, and if it is encountered in a
-configured remote, the first argument is the name of that remote.</p></div>
-<div class="paragraph"><p>Additionally, when a configured remote has <em>remote.<name>.vcs</em> set to
-<em><transport></em>, Git explicitly invokes <em>git remote-<transport></em> with
-<em><name></em> as the first argument. If set, the second argument is
-<em>remote.<name>.url</em>; otherwise, the second argument is omitted.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_input_format">INPUT FORMAT</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Git sends the remote helper a list of commands on standard input, one
-per line. The first command is always the <em>capabilities</em> 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.</p></div>
-<div class="paragraph"><p>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.</p></div>
-<div class="sect2">
-<h3 id="_capabilities">Capabilities</h3>
-<div class="paragraph"><p>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 <code>capabilities</code> command (see COMMANDS, below).</p></div>
-<div class="paragraph"><p>In the following, we list all defined capabilities and for
-each we list which commands a helper with that capability
-must provide.</p></div>
-<div class="sect3">
-<h4 id="_capabilities_for_pushing">Capabilities for Pushing</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<em>connect</em>
-</dt>
-<dd>
-<p>
- Can attempt to connect to <em>git receive-pack</em> (for pushing),
- <em>git upload-pack</em>, etc for communication using
- git’s native packfile protocol. This
- requires a bidirectional, full-duplex connection.
-</p>
-<div class="paragraph"><p>Supported commands: <em>connect</em>.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>push</em>
-</dt>
-<dd>
-<p>
- Can discover remote refs and push local commits and the
- history leading up to them to new or existing remote refs.
-</p>
-<div class="paragraph"><p>Supported commands: <em>list for-push</em>, <em>push</em>.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>export</em>
-</dt>
-<dd>
-<p>
- Can discover remote refs and push specified objects from a
- fast-import stream to remote refs.
-</p>
-<div class="paragraph"><p>Supported commands: <em>list for-push</em>, <em>export</em>.</p></div>
-</dd>
-</dl></div>
-<div class="paragraph"><p>If a helper advertises <em>connect</em>, Git will use it if possible and
-fall back to another capability if the helper requests so when
-connecting (see the <em>connect</em> command under COMMANDS).
-When choosing between <em>push</em> and <em>export</em>, Git prefers <em>push</em>.
-Other frontends may have some other order of preference.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_capabilities_for_fetching">Capabilities for Fetching</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<em>connect</em>
-</dt>
-<dd>
-<p>
- Can try to connect to <em>git upload-pack</em> (for fetching),
- <em>git receive-pack</em>, etc for communication using the
- Git’s native packfile protocol. This
- requires a bidirectional, full-duplex connection.
-</p>
-<div class="paragraph"><p>Supported commands: <em>connect</em>.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>fetch</em>
-</dt>
-<dd>
-<p>
- Can discover remote refs and transfer objects reachable from
- them to the local object store.
-</p>
-<div class="paragraph"><p>Supported commands: <em>list</em>, <em>fetch</em>.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>import</em>
-</dt>
-<dd>
-<p>
- Can discover remote refs and output objects reachable from
- them as a stream in fast-import format.
-</p>
-<div class="paragraph"><p>Supported commands: <em>list</em>, <em>import</em>.</p></div>
-</dd>
-</dl></div>
-<div class="paragraph"><p>If a helper advertises <em>connect</em>, Git will use it if possible and
-fall back to another capability if the helper requests so when
-connecting (see the <em>connect</em> command under COMMANDS).
-When choosing between <em>fetch</em> and <em>import</em>, Git prefers <em>fetch</em>.
-Other frontends may have some other order of preference.</p></div>
-</div>
-<div class="sect3">
-<h4 id="_miscellaneous_capabilities">Miscellaneous capabilities</h4>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<em>option</em>
-</dt>
-<dd>
-<p>
- For specifying settings like <code>verbosity</code> (how much output to
- write to stderr) and <code>depth</code> (how much history is wanted in the
- case of a shallow clone) that affect how other commands are
- carried out.
-</p>
-</dd>
-<dt class="hdlist1">
-<em>refspec</em> <refspec>
-</dt>
-<dd>
-<p>
- This modifies the <em>import</em> 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 <em>import</em>
- capability use this.
-</p>
-<div class="paragraph"><p>A helper advertising the capability
-<code>refspec refs/heads/*:refs/svn/origin/branches/*</code>
-is saying that, when it is asked to <code>import refs/heads/topic</code>, the
-stream it outputs will update the <code>refs/svn/origin/branches/topic</code>
-ref.</p></div>
-<div class="paragraph"><p>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 <em>refspec</em> capability is advertised,
-there is an implied <code>refspec *:*</code>.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>bidi-import</em>
-</dt>
-<dd>
-<p>
- This modifies the <em>import</em> capability.
- The fast-import commands <em>cat-blob</em> and <em>ls</em> 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 <em>bidi-import</em>
- buffer all <em>import</em> 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.
-</p>
-</dd>
-<dt class="hdlist1">
-<em>export-marks</em> <file>
-</dt>
-<dd>
-<p>
- This modifies the <em>export</em> capability, instructing Git to dump the
- internal marks table to <file> when complete. For details,
- read up on <em>--export-marks=<file></em> in <a href="git-fast-export.html">git-fast-export(1)</a>.
-</p>
-</dd>
-<dt class="hdlist1">
-<em>import-marks</em> <file>
-</dt>
-<dd>
-<p>
- This modifies the <em>export</em> capability, instructing Git to load the
- marks specified in <file> before processing any input. For details,
- read up on <em>--import-marks=<file></em> in <a href="git-fast-export.html">git-fast-export(1)</a>.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_commands">COMMANDS</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>Commands are given by the caller on the helper’s standard input, one per line.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<em>capabilities</em>
-</dt>
-<dd>
-<p>
- Lists the capabilities of the helper, one per line, ending
- with a blank line. Each capability may be preceded with <em>*</em>,
- which marks them mandatory for Git versions using the remote
- helper to understand. Any unknown mandatory capability is a
- fatal error.
-</p>
-<div class="paragraph"><p>Support for this command is mandatory.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>list</em>
-</dt>
-<dd>
-<p>
- 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.
-</p>
-<div class="paragraph"><p>See REF LIST ATTRIBUTES for a list of currently defined attributes.</p></div>
-<div class="paragraph"><p>Supported if the helper has the "fetch" or "import" capability.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>list for-push</em>
-</dt>
-<dd>
-<p>
- Similar to <em>list</em>, 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 <em>list</em>
- is going to be used, possibly reducing the amount
- of work that needs to be performed.
-</p>
-<div class="paragraph"><p>Supported if the helper has the "push" or "export" capability.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>option</em> <name> <value>
-</dt>
-<dd>
-<p>
- Sets the transport helper option <name> to <value>. Outputs a
- single line containing one of <em>ok</em> (option successfully set),
- <em>unsupported</em> (option not recognized) or <em>error <msg></em>
- (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.
-</p>
-<div class="paragraph"><p>See OPTIONS for a list of currently defined options.</p></div>
-<div class="paragraph"><p>Supported if the helper has the "option" capability.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>fetch</em> <sha1> <name>
-</dt>
-<dd>
-<p>
- 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 <em>list</em> with a sha1 may be fetched this way.
-</p>
-<div class="paragraph"><p>Optionally may output a <em>lock <file></em> line indicating a file under
-GIT_DIR/objects/pack which is keeping a pack until refs can be
-suitably updated.</p></div>
-<div class="paragraph"><p>Supported if the helper has the "fetch" capability.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>push</em> +<src>:<dst>
-</dt>
-<dd>
-<p>
- Pushes the given local <src> commit or branch to the
- remote branch described by <dst>. A batch sequence of
- one or more <em>push</em> commands is terminated with a blank line
- (if there is only one reference to push, a single <em>push</em> command
- is followed by a blank line). For example, the following would
- be two batches of <em>push</em>, the first asking the remote-helper
- to push the local ref <em>master</em> to the remote ref <em>master</em> and
- the local <em>HEAD</em> to the remote <em>branch</em>, and the second
- asking to push ref <em>foo</em> to ref <em>bar</em> (forced update requested
- by the <em>+</em>).
-</p>
-<div class="listingblock">
-<div class="content">
-<pre><code>push refs/heads/master:refs/heads/master
-push HEAD:refs/heads/branch
-\n
-push +refs/heads/foo:refs/heads/bar
-\n</code></pre>
-</div></div>
-<div class="paragraph"><p>Zero or more protocol options may be entered after the last <em>push</em>
-command, before the batch’s terminating blank line.</p></div>
-<div class="paragraph"><p>When the push is complete, outputs one or more <em>ok <dst></em> or
-<em>error <dst> <why>?</em> 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.</p></div>
-<div class="paragraph"><p>Supported if the helper has the "push" capability.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>import</em> <name>
-</dt>
-<dd>
-<p>
- 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.
-</p>
-<div class="paragraph"><p>Especially useful for interoperability with a foreign versioning
-system.</p></div>
-<div class="paragraph"><p>Just like <em>push</em>, a batch sequence of one or more <em>import</em> is
-terminated with a blank line. For each batch of <em>import</em>, the remote
-helper should produce a fast-import stream terminated by a <em>done</em>
-command.</p></div>
-<div class="paragraph"><p>Note that if the <em>bidi-import</em> 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.</p></div>
-<div class="paragraph"><p>Supported if the helper has the "import" capability.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>export</em>
-</dt>
-<dd>
-<p>
- Instructs the remote helper that any subsequent input is
- part of a fast-import stream (generated by <em>git fast-export</em>)
- containing objects which should be pushed to the remote.
-</p>
-<div class="paragraph"><p>Especially useful for interoperability with a foreign versioning
-system.</p></div>
-<div class="paragraph"><p>The <em>export-marks</em> and <em>import-marks</em> capabilities, if specified,
-affect this command in so far as they are passed on to <em>git
-fast-export</em>, which then will load/store a table of marks for
-local objects. This can be used to implement for incremental
-operations.</p></div>
-<div class="paragraph"><p>Supported if the helper has the "export" capability.</p></div>
-</dd>
-<dt class="hdlist1">
-<em>connect</em> <service>
-</dt>
-<dd>
-<p>
- 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 <em>git-upload-pack</em>
- as service) on remote side. Valid replies to this command are
- empty line (connection established), <em>fallback</em> (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.
-</p>
-<div class="paragraph"><p>Supported if the helper has the "connect" capability.</p></div>
-</dd>
-</dl></div>
-<div class="paragraph"><p>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.</p></div>
-<div class="paragraph"><p>Additional commands may be supported, as may be determined from
-capabilities reported by the helper.</p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_ref_list_attributes">REF LIST ATTRIBUTES</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The <em>list</em> 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.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<em>unchanged</em>
-</dt>
-<dd>
-<p>
- This ref is unchanged since the last import or fetch, although
- the helper cannot necessarily determine what value that produced.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_options">OPTIONS</h2>
-<div class="sectionbody">
-<div class="paragraph"><p>The following options are defined and (under suitable circumstances)
-set by Git if the remote helper has the <em>option</em> capability.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<em>option verbosity</em> <n>
-</dt>
-<dd>
-<p>
- 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.
-</p>
-</dd>
-<dt class="hdlist1">
-<em>option progress</em> {<em>true</em>|<em>false</em>}
-</dt>
-<dd>
-<p>
- Enables (or disables) progress messages displayed by the
- transport helper during a command.
-</p>
-</dd>
-<dt class="hdlist1">
-<em>option depth</em> <depth>
-</dt>
-<dd>
-<p>
- Deepens the history of a shallow repository.
-</p>
-</dd>
-<dt class="hdlist1">
-<em>option followtags</em> {<em>true</em>|<em>false</em>}
-</dt>
-<dd>
-<p>
- 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.
-</p>
-</dd>
-</dl></div>
-<div class="paragraph"><p><em>option dry-run</em> {<em>true</em>|<em>false</em>}:
- If true, pretend the operation completed successfully,
- but don’t actually change any repository data. For most
- helpers this only applies to the <em>push</em>, if supported.</p></div>
-<div class="dlist"><dl>
-<dt class="hdlist1">
-<em>option servpath <c-style-quoted-path></em>
-</dt>
-<dd>
-<p>
- 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.
-</p>
-</dd>
-</dl></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_see_also">SEE ALSO</h2>
-<div class="sectionbody">
-<div class="paragraph"><p><a href="git-remote.html">git-remote(1)</a></p></div>
-<div class="paragraph"><p><a href="git-remote-testgit.html">git-remote-testgit(1)</a></p></div>
-</div>
-</div>
-<div class="sect1">
-<h2 id="_git">GIT</h2>
+<div id="preamble">
<div class="sectionbody">
-<div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
+<div class="paragraph"><p>This document has been moved to <a href="gitremote-helpers.html">gitremote-helpers(1)</a>.</p></div>
+<div class="paragraph"><p>Please let the owners of the referring site know so that they can update the
+link you clicked to get here.</p></div>
+<div class="paragraph"><p>Thanks.</p></div>
</div>
</div>
</div>
<div id="footnotes"><hr /></div>
<div id="footer">
<div id="footer-text">
-Last updated 2013-02-05 21:07:26 PST
+Last updated 2013-02-07 16:01:27 PST
</div>
</div>
</body>
|