Hi Stolee, While catching up with stuff I missed, I saw two minor nits for future updates, when reading the docs on GfW. On 09/08/2022 14:12, Derrick Stolee via GitGitGadget wrote: > From: Derrick Stolee <derrickstolee@xxxxxxxxxx> > > Introduce the idea of bundle URIs to the Git codebase through an > aspirational design document. This document includes the full design > intended to include the feature in its fully-implemented form. This will > take several steps as detailed in the Implementation Plan section. > > By committing this document now, it can be used to motivate changes > necessary to reach these final goals. The design can still be altered as > new information is discovered. > > Signed-off-by: Derrick Stolee <derrickstolee@xxxxxxxxxx> > --- > [...] > diff --git a/Documentation/technical/bundle-uri.txt b/Documentation/technical/bundle-uri.txt > new file mode 100644 > index 00000000000..e6d63b868b8 > --- /dev/null > +++ b/Documentation/technical/bundle-uri.txt > @@ -0,0 +1,468 @@ > +Bundle URIs > +=========== > + [...] > + > +bundle.<id>.creationToken:: > + This value is a nonnegative 64-bit integer used for sorting the bundles > + the list. s/the // .. an extraneous 'the' ? > This is used to download a subset of bundles during a fetch > + when `bundle.heuristic=creationToken`. > + > +bundle.<id>.location:: > + This string value advertises a real-world location from where the bundle > + URI is served. This can be used to present the user with an option for > + which bundle URI to use or simply as an informative indicator of which > + bundle URI was selected by Git. This is only valuable when > + `bundle.mode` is `any`. > + [...] > +Cloning with Bundle URIs > +------------------------ > + > +The primary need for bundle URIs is to speed up clones. The Git client > +will interact with bundle URIs according to the following flow: > + > +1. The user specifies a bundle URI with the `--bundle-uri` command-line > + option _or_ the client discovers a bundle list advertised by the > + Git server. > + > +2. If the downloaded data from a bundle URI is a bundle, then the client > + inspects the bundle headers to check that the prerequisite commit OIDs > + are present in the client repository. If some are missing, then the > + client delays unbundling until other bundles have been unbundled, > + making those OIDs present. When all required OIDs are present, the > + client unbundles that data using a refspec. The default refspec is > + `+refs/heads/*:refs/bundles/*`, but this can be configured. These refs > + are stored so that later `git fetch` negotiations can communicate the > + bundled refs as `have`s, reducing the size of the fetch over the Git s/ave`s/ave` 's/ .. The backtick is mistaken for an apostrophe and then is misformatted for the Git for Windows HTML versions, e.g. https://github.com/gitster/git-htmldocs/blob/master/technical/bundle-uri.html#L1056 > + protocol. To allow pruning refs from this ref namespace, Git may > + introduce a numbered namespace (such as `refs/bundles/<i>/*`) such that > + stale bundle refs can be deleted. > + [...] Quite readable. Thanks. Philip
