1#@!#!123s

: / proc / self / root / usr / share / doc / git / technical /

Filename : packfile-uri.txt

back

Packfile URIs
=============

This feature allows servers to serve part of their packfile response as URIs.
This allows server designs that improve scalability in bandwidth and CPU usage
(for example, by serving some data through a CDN), and (in the future) provides
some measure of resumability to clients.

This feature is available only in protocol version 2.

Protocol
--------

The server advertises the `packfile-uris` capability.

If the client then communicates which protocols (HTTPS, etc.) it supports with
a `packfile-uris` argument, the server MAY send a `packfile-uris` section
directly before the `packfile` section (right after `wanted-refs` if it is
sent) containing URIs of any of the given protocols. The URIs point to
packfiles that use only features that the client has declared that it supports
(e.g. ofs-delta and thin-pack). See linkgit:gitprotocol-v2[5] for the documentation of
this section.

Clients should then download and index all the given URIs (in addition to
downloading and indexing the packfile given in the `packfile` section of the
response) before performing the connectivity check.

Server design
-------------

The server can be trivially made compatible with the proposed protocol by
having it advertise `packfile-uris`, tolerating the client sending
`packfile-uris`, and never sending any `packfile-uris` section. But we should
include some sort of non-trivial implementation in the Minimum Viable Product,
at least so that we can test the client.

This is the implementation: a feature, marked experimental, that allows the
server to be configured by one or more `uploadpack.blobPackfileUri=
<object-hash> <pack-hash> <uri>` entries. Whenever the list of objects to be
sent is assembled, all such blobs are excluded, replaced with URIs. As noted
in "Future work" below, the server can evolve in the future to support
excluding other objects (or other implementations of servers could be made
that support excluding other objects) without needing a protocol change, so
clients should not expect that packfiles downloaded in this way only contain
single blobs.

Client design
-------------

The client has a config variable `fetch.uriprotocols` that determines which
protocols the end user is willing to use. By default, this is empty.

When the client downloads the given URIs, it should store them with "keep"
files, just like it does with the packfile in the `packfile` section. These
additional "keep" files can only be removed after the refs have been updated -
just like the "keep" file for the packfile in the `packfile` section.

The division of work (initial fetch + additional URIs) introduces convenient
points for resumption of an interrupted clone - such resumption can be done
after the Minimum Viable Product (see "Future work").

Future work
-----------

The protocol design allows some evolution of the server and client without any
need for protocol changes, so only a small-scoped design is included here to
form the MVP. For example, the following can be done:

 * On the server, more sophisticated means of excluding objects (e.g. by
   specifying a commit to represent that commit and all objects that it
   references).
 * On the client, resumption of clone. If a clone is interrupted, information
   could be recorded in the repository's config and a "clone-resume" command
   can resume the clone in progress. (Resumption of subsequent fetches is more
   difficult because that must deal with the user wanting to use the repository
   even after the fetch was interrupted.)

There are some possible features that will require a change in protocol:

 * Additional HTTP headers (e.g. authentication)
 * Byte range support
 * Different file formats referenced by URIs (e.g. raw object)

Name	Size	Last Modified	Owner	Permissions
api-error-handling.html	21.737 KB	December 17 2024 4:16:43	root	0644
api-error-handling.txt	3.729 KB	May 31 2024 12:41:06	root	0644
api-index-skel.txt	0.422 KB	May 31 2024 12:41:06	root	0644
api-index.html	16.78 KB	December 17 2024 4:18:10	root	0644
api-index.sh	0.597 KB	May 31 2024 12:41:06	root	0644
api-index.txt	0.633 KB	December 17 2024 4:16:46	root	0644
api-merge.html	17.876 KB	December 17 2024 4:16:43	root	0644
api-merge.txt	1.064 KB	May 31 2024 12:41:06	root	0644
api-parse-options.html	35.798 KB	December 17 2024 4:16:44	root	0644
api-parse-options.txt	12.849 KB	May 31 2024 12:41:06	root	0644
api-simple-ipc.html	21.863 KB	December 17 2024 4:16:43	root	0644
api-simple-ipc.txt	4.738 KB	May 31 2024 12:41:06	root	0644
api-trace2.html	75.8 KB	December 17 2024 4:16:44	root	0644
api-trace2.txt	43.218 KB	May 31 2024 12:41:06	root	0644
bitmap-format.html	29.69 KB	December 17 2024 4:16:45	root	0644
bitmap-format.txt	8.663 KB	May 31 2024 12:41:06	root	0644
bundle-uri.html	50.183 KB	December 17 2024 4:16:45	root	0644
bundle-uri.txt	26.159 KB	May 31 2024 12:41:06	root	0644
commit-graph.txt	17.536 KB	May 31 2024 12:41:06	root	0644
directory-rename-detection.txt	5.077 KB	May 31 2024 12:41:06	root	0644
hash-function-transition.html	63.026 KB	December 17 2024 4:16:45	root	0644
hash-function-transition.txt	35.053 KB	May 31 2024 12:41:06	root	0644
long-running-process-protocol.html	18.55 KB	December 17 2024 4:16:45	root	0644
long-running-process-protocol.txt	1.884 KB	May 31 2024 12:41:06	root	0644
multi-pack-index.html	21.936 KB	December 17 2024 4:16:45	root	0644
multi-pack-index.txt	4.354 KB	May 31 2024 12:41:06	root	0644
pack-heuristics.html	42.572 KB	December 17 2024 4:16:46	root	0644
pack-heuristics.txt	17.617 KB	May 31 2024 12:41:06	root	0644
packfile-uri.txt	3.66 KB	May 31 2024 12:41:06	root	0644
parallel-checkout.html	30.972 KB	December 17 2024 4:16:45	root	0644
parallel-checkout.txt	12.013 KB	May 31 2024 12:41:06	root	0644
partial-clone.html	35.641 KB	December 17 2024 4:16:46	root	0644
partial-clone.txt	14.617 KB	May 31 2024 12:41:06	root	0644
racy-git.html	27.339 KB	December 17 2024 4:16:46	root	0644
racy-git.txt	8.907 KB	May 31 2024 12:41:06	root	0644
reftable.html	72.063 KB	December 17 2024 4:16:46	root	0644
reftable.txt	36.646 KB	May 31 2024 12:41:06	root	0644
remembering-renames.txt	29.648 KB	May 31 2024 12:41:06	root	0644
repository-version.txt	4.21 KB	May 31 2024 12:41:06	root	0644
rerere.txt	6.357 KB	May 31 2024 12:41:06	root	0644
scalar.html	19.979 KB	December 17 2024 4:16:46	root	0644
scalar.txt	2.866 KB	May 31 2024 12:41:06	root	0644
send-pack-pipeline.html	18.862 KB	December 17 2024 4:16:46	root	0644
send-pack-pipeline.txt	1.923 KB	May 31 2024 12:41:06	root	0644
shallow.html	19.224 KB	December 17 2024 4:16:46	root	0644
shallow.txt	2.488 KB	May 31 2024 12:41:06	root	0644
sparse-checkout.txt	46.386 KB	May 31 2024 12:41:06	root	0644
sparse-index.txt	9.278 KB	May 31 2024 12:41:06	root	0644
trivial-merge.html	21.751 KB	December 17 2024 4:16:46	root	0644
trivial-merge.txt	4.164 KB	May 31 2024 12:41:06	root	0644

2017 © D7net \| D704T team