Autogenerated HTML docs for v2.39.0-158-g2b4f5

1 files changed, 223 insertions, 1 deletions

diff --git a/gitprotocol-v2.html b/gitprotocol-v2.html
index a4ff6ee1f..a49b2fbaf 100644
--- a/gitprotocol-v2.html
+++ b/gitprotocol-v2.html
@@ -1484,6 +1484,228 @@ and associated requested information, each separated by a single space.</p></div
 <pre><code>obj-info = obj-id SP obj-size</code></pre>

 </div></div>

 </div>

+<div class="sect2">

+<h3 id="_bundle_uri">bundle-uri</h3>

+<div class="paragraph"><p>If the <em>bundle-uri</em> capability is advertised, the server supports the

+&#8216;bundle-uri&#8217; command.</p></div>

+<div class="paragraph"><p>The capability is currently advertised with no value (i.e. not

+"bundle-uri=somevalue"), a value may be added in the future for

+supporting command-wide extensions. Clients MUST ignore any unknown

+capability values and proceed with the 'bundle-uri` dialog they

+support.</p></div>

+<div class="paragraph"><p>The <em>bundle-uri</em> command is intended to be issued before <code>fetch</code> to

+get URIs to bundle files (see <a href="git-bundle.html">git-bundle(1)</a>) to "seed" and

+inform the subsequent <code>fetch</code> command.</p></div>

+<div class="paragraph"><p>The client CAN issue <code>bundle-uri</code> before or after any other valid

+command. To be useful to clients it&#8217;s expected that it&#8217;ll be issued

+after an <code>ls-refs</code> and before <code>fetch</code>, but CAN be issued at any time

+in the dialog.</p></div>

+<div class="sect3">

+<h4 id="_discussion_of_bundle_uri">DISCUSSION of bundle-uri</h4>

+<div class="paragraph"><p>The intent of the feature is optimize for server resource consumption

+in the common case by changing the common case of fetching a very

+large PACK during <a href="git-clone.html">git-clone(1)</a> into a smaller incremental

+fetch.</p></div>

+<div class="paragraph"><p>It also allows servers to achieve better caching in combination with

+an <code>uploadpack.packObjectsHook</code> (see <a href="git-config.html">git-config(1)</a>).</p></div>

+<div class="paragraph"><p>By having new clones or fetches be a more predictable and common

+negotiation against the tips of recently produces *.bundle file(s).

+Servers might even pre-generate the results of such negotiations for

+the <code>uploadpack.packObjectsHook</code> as new pushes come in.</p></div>

+<div class="paragraph"><p>One way that servers could take advantage of these bundles is that the

+server would anticipate that fresh clones will download a known bundle,

+followed by catching up to the current state of the repository using ref

+tips found in that bundle (or bundles).</p></div>

+</div>

+<div class="sect3">

+<h4 id="_protocol_for_bundle_uri">PROTOCOL for bundle-uri</h4>

+<div class="paragraph"><p>A <code>bundle-uri</code> request takes no arguments, and as noted above does not

+currently advertise a capability value. Both may be added in the

+future.</p></div>

+<div class="paragraph"><p>When the client issues a <code>command=bundle-uri</code> request, the response is a

+list of key-value pairs provided as packet lines with value

+<code>&lt;key&gt;=&lt;value&gt;</code>. Each <code>&lt;key&gt;</code> should be interpreted as a config key from

+the <code>bundle.*</code> namespace to construct a list of bundles. These keys are

+grouped by a <code>bundle.&lt;id&gt;.</code> subsection, where each key corresponding to a

+given <code>&lt;id&gt;</code> contributes attributes to the bundle defined by that <code>&lt;id&gt;</code>.

+See <a href="git-config.html">git-config(1)</a> for the specific details of these keys and how

+the Git client will interpret their values.</p></div>

+<div class="paragraph"><p>Clients MUST parse the line according to the above format, lines that do

+not conform to the format SHOULD be discarded. The user MAY be warned in

+such a case.</p></div>

+</div>

+<div class="sect3">

+<h4 id="_bundle_uri_client_and_server_expectations">bundle-uri CLIENT AND SERVER EXPECTATIONS</h4>

+<div class="dlist"><dl>

+<dt class="hdlist1">

+URI CONTENTS

+</dt>

+<dd>

+<p>

+The content at the advertised URIs MUST be one of two types.

+</p>

+<div class="paragraph"><p>The advertised URI may contain a bundle file that <code>git bundle verify</code>

+would accept. I.e. they MUST contain one or more reference tips for

+use by the client, MUST indicate prerequisites (in any) with standard

+"-" prefixes, and MUST indicate their "object-format", if

+applicable.</p></div>

+<div class="paragraph"><p>The advertised URI may alternatively contain a plaintext file that <code>git

+config --list</code> would accept (with the <code>--file</code> option). The key-value

+pairs in this list are in the <code>bundle.*</code> namespace (see

+<a href="git-config.html">git-config(1)</a>).</p></div>

+</dd>

+<dt class="hdlist1">

+bundle-uri CLIENT ERROR RECOVERY

+</dt>

+<dd>

+<p>

+A client MUST above all gracefully degrade on errors, whether that

+error is because of bad missing/data in the bundle URI(s), because

+that client is too dumb to e.g. understand and fully parse out bundle

+headers and their prerequisite relationships, or something else.

+</p>

+<div class="paragraph"><p>Server operators should feel confident in turning on "bundle-uri" and

+not worry if e.g. their CDN goes down that clones or fetches will run

+into hard failures. Even if the server bundle bundle(s) are

+incomplete, or bad in some way the client should still end up with a

+functioning repository, just as if it had chosen not to use this

+protocol extension.</p></div>

+<div class="paragraph"><p>All subsequent discussion on client and server interaction MUST keep

+this in mind.</p></div>

+</dd>

+<dt class="hdlist1">

+bundle-uri SERVER TO CLIENT

+</dt>

+<dd>

+<p>

+The ordering of the returned bundle uris is not significant. Clients

+MUST parse their headers to discover their contained OIDS and

+prerequisites. A client MUST consider the content of the bundle(s)

+themselves and their header as the ultimate source of truth.

+</p>

+<div class="paragraph"><p>A server MAY even return bundle(s) that don&#8217;t have any direct

+relationship to the repository being cloned (either through accident,

+or intentional "clever" configuration), and expect a client to sort

+out what data they&#8217;d like from the bundle(s), if any.</p></div>

+</dd>

+<dt class="hdlist1">

+bundle-uri CLIENT TO SERVER

+</dt>

+<dd>

+<p>

+The client SHOULD provide reference tips found in the bundle header(s)

+as <em>have</em> lines in any subsequent <code>fetch</code> request. A client MAY also

+ignore the bundle(s) entirely if doing so is deemed worse for some

+reason, e.g. if the bundles can&#8217;t be downloaded, it doesn&#8217;t like the

+tips it finds etc.

+</p>

+</dd>

+<dt class="hdlist1">

+WHEN ADVERTISED BUNDLE(S) REQUIRE NO FURTHER NEGOTIATION

+</dt>

+<dd>

+<p>

+If after issuing <code>bundle-uri</code> and <code>ls-refs</code>, and getting the header(s)

+of the bundle(s) the client finds that the ref tips it wants can be

+retrieved entirely from advertised bundle(s), the client MAY disconnect

+from the Git server. The results of such a <em>clone</em> or <em>fetch</em> should be

+indistinguishable from the state attained without using bundle-uri.

+</p>

+</dd>

+<dt class="hdlist1">

+EARLY CLIENT DISCONNECTIONS AND ERROR RECOVERY

+</dt>

+<dd>

+<p>

+A client MAY perform an early disconnect while still downloading the

+bundle(s) (having streamed and parsed their headers). In such a case

+the client MUST gracefully recover from any errors related to

+finishing the download and validation of the bundle(s).

+</p>

+<div class="paragraph"><p>I.e. a client might need to re-connect and issue a <em>fetch</em> command,

+and possibly fall back to not making use of <em>bundle-uri</em> at all.</p></div>

+<div class="paragraph"><p>This "MAY" behavior is specified as such (and not a "SHOULD") on the

+assumption that a server advertising bundle uris is more likely than

+not to be serving up a relatively large repository, and to be pointing

+to URIs that have a good chance of being in working order. A client

+MAY e.g. look at the payload size of the bundles as a heuristic to see

+if an early disconnect is worth it, should falling back on a full

+"fetch" dialog be necessary.</p></div>

+</dd>

+<dt class="hdlist1">

+WHEN ADVERTISED BUNDLE(S) REQUIRE FURTHER NEGOTIATION

+</dt>

+<dd>

+<p>

+A client SHOULD commence a negotiation of a PACK from the server via

+the "fetch" command using the OID tips found in advertised bundles,

+even if&#8217;s still in the process of downloading those bundle(s).

+</p>

+<div class="paragraph"><p>This allows for aggressive early disconnects from any interactive

+server dialog. The client blindly trusts that the advertised OID tips

+are relevant, and issues them as <em>have</em> lines, it then requests any

+tips it would like (usually from the "ls-refs" advertisement) via

+<em>want</em> lines. The server will then compute a (hopefully small) PACK

+with the expected difference between the tips from the bundle(s) and

+the data requested.</p></div>

+<div class="paragraph"><p>The only connection the client then needs to keep active is to the

+concurrently downloading static bundle(s), when those and the

+incremental PACK are retrieved they should be inflated and

+validated. Any errors at this point should be gracefully recovered

+from, see above.</p></div>

+</dd>

+</dl></div>

+</div>

+<div class="sect3">

+<h4 id="_bundle_uri_protocol_features">bundle-uri PROTOCOL FEATURES</h4>

+<div class="paragraph"><p>The client constructs a bundle list from the <code>&lt;key&gt;=&lt;value&gt;</code> pairs

+provided by the server. These pairs are part of the <code>bundle.*</code> namespace

+as documented in <a href="git-config.html">git-config(1)</a>. In this section, we discuss some

+of these keys and describe the actions the client will do in response to

+this information.</p></div>

+<div class="paragraph"><p>In particular, the <code>bundle.version</code> key specifies an integer value. The

+only accepted value at the moment is <code>1</code>, but if the client sees an

+unexpected value here then the client MUST ignore the bundle list.</p></div>

+<div class="paragraph"><p>As long as <code>bundle.version</code> is understood, all other unknown keys MAY be

+ignored by the client. The server will guarantee compatibility with older

+clients, though newer clients may be better able to use the extra keys to

+minimize downloads.</p></div>

+<div class="paragraph"><p>Any backwards-incompatible addition of pre-URI key-value will be

+guarded by a new <code>bundle.version</code> value or values in <em>bundle-uri</em>

+capability advertisement itself, and/or by new future <code>bundle-uri</code>

+request arguments.</p></div>

+<div class="paragraph"><p>Some example key-value pairs that are not currently implemented but could

+be implemented in the future include:</p></div>

+<div class="ulist"><ul>

+<li>

+<p>

+Add a "hash=&lt;val&gt;" or "size=&lt;bytes&gt;" advertise the expected hash or

+   size of the bundle file.

+</p>

+</li>

+<li>

+<p>

+Advertise that one or more bundle files are the same (to e.g. have

+   clients round-robin or otherwise choose one of N possible files).

+</p>

+</li>

+<li>

+<p>

+A "oid=&lt;OID&gt;" shortcut and "prerequisite=&lt;OID&gt;" shortcut. For

+   expressing the common case of a bundle with one tip and no

+   prerequisites, or one tip and one prerequisite.

+</p>

+<div class="paragraph"><p>This would allow for optimizing the common case of servers who&#8217;d like

+to provide one "big bundle" containing only their "main" branch,

+and/or incremental updates thereof.</p></div>

+<div class="paragraph"><p>A client receiving such a a response MAY assume that they can skip

+retrieving the header from a bundle at the indicated URI, and thus

+save themselves and the server(s) the request(s) needed to inspect the

+headers of that bundle or bundles.</p></div>

+</li>

+</ul></div>

+</div>

+</div>

 </div>

 </div>

 <div class="sect1">

@@ -1497,7 +1719,7 @@ and associated requested information, each separated by a single space.</p></div
 <div id="footer">

 <div id="footer-text">

 Last updated

- 2022-09-22 07:44:34 JST

+ 2023-01-02 22:37:31 JST

 </div>

 </div>

 </body>