FM / technical

/usr/share/doc/git/technical

Name	Size	Mode	Actions
api-error-handling.html	22259	0644	edit dl rm
api-error-handling.txt	3818	0644	edit dl rm
api-index-skel.txt	432	0644	edit dl rm
api-index.html	17183	0644	edit dl rm
api-index.sh	611	0644	edit dl rm
api-index.txt	648	0644	edit dl rm
api-merge.html	18305	0644	edit dl rm
api-merge.txt	1090	0644	edit dl rm
api-parse-options.html	36657	0644	edit dl rm
api-parse-options.txt	13157	0644	edit dl rm
api-simple-ipc.html	22388	0644	edit dl rm
api-simple-ipc.txt	4852	0644	edit dl rm
api-trace2.html	77619	0644	edit dl rm
api-trace2.txt	44255	0644	edit dl rm
bitmap-format.html	30403	0644	edit dl rm
bitmap-format.txt	8871	0644	edit dl rm
bundle-uri.html	51387	0644	edit dl rm
bundle-uri.txt	26787	0644	edit dl rm
commit-graph.txt	17957	0644	edit dl rm
directory-rename-detection.txt	5199	0644	edit dl rm
hash-function-transition.html	64539	0644	edit dl rm
hash-function-transition.txt	35894	0644	edit dl rm
long-running-process-protocol.html	18995	0644	edit dl rm
long-running-process-protocol.txt	1929	0644	edit dl rm
multi-pack-index.html	22462	0644	edit dl rm
multi-pack-index.txt	4459	0644	edit dl rm
pack-heuristics.html	43594	0644	edit dl rm
pack-heuristics.txt	18040	0644	edit dl rm
packfile-uri.txt	3748	0644	edit dl rm
parallel-checkout.html	31715	0644	edit dl rm
parallel-checkout.txt	12301	0644	edit dl rm
partial-clone.html	36496	0644	edit dl rm
partial-clone.txt	14968	0644	edit dl rm
racy-git.html	27995	0644	edit dl rm
racy-git.txt	9121	0644	edit dl rm
reftable.html	73792	0644	edit dl rm
reftable.txt	37525	0644	edit dl rm
remembering-renames.txt	30360	0644	edit dl rm
repository-version.txt	4311	0644	edit dl rm
rerere.txt	6510	0644	edit dl rm
scalar.html	20458	0644	edit dl rm
scalar.txt	2935	0644	edit dl rm
send-pack-pipeline.html	19315	0644	edit dl rm
send-pack-pipeline.txt	1969	0644	edit dl rm
shallow.html	19685	0644	edit dl rm
shallow.txt	2548	0644	edit dl rm
sparse-checkout.txt	47499	0644	edit dl rm
sparse-index.txt	9501	0644	edit dl rm
trivial-merge.html	22273	0644	edit dl rm
trivial-merge.txt	4264	0644	edit dl rm

Edit: /usr/share/doc/git/technical/packfile-uri.txt (3748B)

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)

cmd: