technical/partial-clone.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   5 <head>
   6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
   7 <meta name="generator" content="AsciiDoc 10.2.0" />
   8 <title>Partial Clone Design Notes</title>
   9 <style type="text/css">
  10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
  11
  12 /* Default font. */
  13 body {
  14   font-family: Georgia,serif;
  15 }
  16
  17 /* Title font. */
  18 h1, h2, h3, h4, h5, h6,
  19 div.title, caption.title,
  20 thead, p.table.header,
  21 #toctitle,
  22 #author, #revnumber, #revdate, #revremark,
  23 #footer {
  24   font-family: Arial,Helvetica,sans-serif;
  25 }
  26
  27 body {
  28   margin: 1em 5% 1em 5%;
  29 }
  30
  31 a {
  32   color: blue;
  33   text-decoration: underline;
  34 }
  35 a:visited {
  36   color: fuchsia;
  37 }
  38
  39 em {
  40   font-style: italic;
  41   color: navy;
  42 }
  43
  44 strong {
  45   font-weight: bold;
  46   color: #083194;
  47 }
  48
  49 h1, h2, h3, h4, h5, h6 {
  50   color: #527bbd;
  51   margin-top: 1.2em;
  52   margin-bottom: 0.5em;
  53   line-height: 1.3;
  54 }
  55
  56 h1, h2, h3 {
  57   border-bottom: 2px solid silver;
  58 }
  59 h2 {
  60   padding-top: 0.5em;
  61 }
  62 h3 {
  63   float: left;
  64 }
  65 h3 + * {
  66   clear: left;
  67 }
  68 h5 {
  69   font-size: 1.0em;
  70 }
  71
  72 div.sectionbody {
  73   margin-left: 0;
  74 }
  75
  76 hr {
  77   border: 1px solid silver;
  78 }
  79
  80 p {
  81   margin-top: 0.5em;
  82   margin-bottom: 0.5em;
  83 }
  84
  85 ul, ol, li > p {
  86   margin-top: 0;
  87 }
  88 ul > li     { color: #aaa; }
  89 ul > li > * { color: black; }
  90
  91 .monospaced, code, pre {
  92   font-family: "Courier New", Courier, monospace;
  93   font-size: inherit;
  94   color: navy;
  95   padding: 0;
  96   margin: 0;
  97 }
  98 pre {
  99   white-space: pre-wrap;
 100 }
 101
 102 #author {
 103   color: #527bbd;
 104   font-weight: bold;
 105   font-size: 1.1em;
 106 }
 107 #email {
 108 }
 109 #revnumber, #revdate, #revremark {
 110 }
 111
 112 #footer {
 113   font-size: small;
 114   border-top: 2px solid silver;
 115   padding-top: 0.5em;
 116   margin-top: 4.0em;
 117 }
 118 #footer-text {
 119   float: left;
 120   padding-bottom: 0.5em;
 121 }
 122 #footer-badges {
 123   float: right;
 124   padding-bottom: 0.5em;
 125 }
 126
 127 #preamble {
 128   margin-top: 1.5em;
 129   margin-bottom: 1.5em;
 130 }
 131 div.imageblock, div.exampleblock, div.verseblock,
 132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 133 div.admonitionblock {
 134   margin-top: 1.0em;
 135   margin-bottom: 1.5em;
 136 }
 137 div.admonitionblock {
 138   margin-top: 2.0em;
 139   margin-bottom: 2.0em;
 140   margin-right: 10%;
 141   color: #606060;
 142 }
 143
 144 div.content { /* Block element content. */
 145   padding: 0;
 146 }
 147
 148 /* Block element titles. */
 149 div.title, caption.title {
 150   color: #527bbd;
 151   font-weight: bold;
 152   text-align: left;
 153   margin-top: 1.0em;
 154   margin-bottom: 0.5em;
 155 }
 156 div.title + * {
 157   margin-top: 0;
 158 }
 159
 160 td div.title:first-child {
 161   margin-top: 0.0em;
 162 }
 163 div.content div.title:first-child {
 164   margin-top: 0.0em;
 165 }
 166 div.content + div.title {
 167   margin-top: 0.0em;
 168 }
 169
 170 div.sidebarblock > div.content {
 171   background: #ffffee;
 172   border: 1px solid #dddddd;
 173   border-left: 4px solid #f0f0f0;
 174   padding: 0.5em;
 175 }
 176
 177 div.listingblock > div.content {
 178   border: 1px solid #dddddd;
 179   border-left: 5px solid #f0f0f0;
 180   background: #f8f8f8;
 181   padding: 0.5em;
 182 }
 183
 184 div.quoteblock, div.verseblock {
 185   padding-left: 1.0em;
 186   margin-left: 1.0em;
 187   margin-right: 10%;
 188   border-left: 5px solid #f0f0f0;
 189   color: #888;
 190 }
 191
 192 div.quoteblock > div.attribution {
 193   padding-top: 0.5em;
 194   text-align: right;
 195 }
 196
 197 div.verseblock > pre.content {
 198   font-family: inherit;
 199   font-size: inherit;
 200 }
 201 div.verseblock > div.attribution {
 202   padding-top: 0.75em;
 203   text-align: left;
 204 }
 205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 206 div.verseblock + div.attribution {
 207   text-align: left;
 208 }
 209
 210 div.admonitionblock .icon {
 211   vertical-align: top;
 212   font-size: 1.1em;
 213   font-weight: bold;
 214   text-decoration: underline;
 215   color: #527bbd;
 216   padding-right: 0.5em;
 217 }
 218 div.admonitionblock td.content {
 219   padding-left: 0.5em;
 220   border-left: 3px solid #dddddd;
 221 }
 222
 223 div.exampleblock > div.content {
 224   border-left: 3px solid #dddddd;
 225   padding-left: 0.5em;
 226 }
 227
 228 div.imageblock div.content { padding-left: 0; }
 229 span.image img { border-style: none; vertical-align: text-bottom; }
 230 a.image:visited { color: white; }
 231
 232 dl {
 233   margin-top: 0.8em;
 234   margin-bottom: 0.8em;
 235 }
 236 dt {
 237   margin-top: 0.5em;
 238   margin-bottom: 0;
 239   font-style: normal;
 240   color: navy;
 241 }
 242 dd > *:first-child {
 243   margin-top: 0.1em;
 244 }
 245
 246 ul, ol {
 247     list-style-position: outside;
 248 }
 249 ol.arabic {
 250   list-style-type: decimal;
 251 }
 252 ol.loweralpha {
 253   list-style-type: lower-alpha;
 254 }
 255 ol.upperalpha {
 256   list-style-type: upper-alpha;
 257 }
 258 ol.lowerroman {
 259   list-style-type: lower-roman;
 260 }
 261 ol.upperroman {
 262   list-style-type: upper-roman;
 263 }
 264
 265 div.compact ul, div.compact ol,
 266 div.compact p, div.compact p,
 267 div.compact div, div.compact div {
 268   margin-top: 0.1em;
 269   margin-bottom: 0.1em;
 270 }
 271
 272 tfoot {
 273   font-weight: bold;
 274 }
 275 td > div.verse {
 276   white-space: pre;
 277 }
 278
 279 div.hdlist {
 280   margin-top: 0.8em;
 281   margin-bottom: 0.8em;
 282 }
 283 div.hdlist tr {
 284   padding-bottom: 15px;
 285 }
 286 dt.hdlist1.strong, td.hdlist1.strong {
 287   font-weight: bold;
 288 }
 289 td.hdlist1 {
 290   vertical-align: top;
 291   font-style: normal;
 292   padding-right: 0.8em;
 293   color: navy;
 294 }
 295 td.hdlist2 {
 296   vertical-align: top;
 297 }
 298 div.hdlist.compact tr {
 299   margin: 0;
 300   padding-bottom: 0;
 301 }
 302
 303 .comment {
 304   background: yellow;
 305 }
 306
 307 .footnote, .footnoteref {
 308   font-size: 0.8em;
 309 }
 310
 311 span.footnote, span.footnoteref {
 312   vertical-align: super;
 313 }
 314
 315 #footnotes {
 316   margin: 20px 0 20px 0;
 317   padding: 7px 0 0 0;
 318 }
 319
 320 #footnotes div.footnote {
 321   margin: 0 0 5px 0;
 322 }
 323
 324 #footnotes hr {
 325   border: none;
 326   border-top: 1px solid silver;
 327   height: 1px;
 328   text-align: left;
 329   margin-left: 0;
 330   width: 20%;
 331   min-width: 100px;
 332 }
 333
 334 div.colist td {
 335   padding-right: 0.5em;
 336   padding-bottom: 0.3em;
 337   vertical-align: top;
 338 }
 339 div.colist td img {
 340   margin-top: 0.3em;
 341 }
 342
 343 @media print {
 344   #footer-badges { display: none; }
 345 }
 346
 347 #toc {
 348   margin-bottom: 2.5em;
 349 }
 350
 351 #toctitle {
 352   color: #527bbd;
 353   font-size: 1.1em;
 354   font-weight: bold;
 355   margin-top: 1.0em;
 356   margin-bottom: 0.1em;
 357 }
 358
 359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 360   margin-top: 0;
 361   margin-bottom: 0;
 362 }
 363 div.toclevel2 {
 364   margin-left: 2em;
 365   font-size: 0.9em;
 366 }
 367 div.toclevel3 {
 368   margin-left: 4em;
 369   font-size: 0.9em;
 370 }
 371 div.toclevel4 {
 372   margin-left: 6em;
 373   font-size: 0.9em;
 374 }
 375
 376 span.aqua { color: aqua; }
 377 span.black { color: black; }
 378 span.blue { color: blue; }
 379 span.fuchsia { color: fuchsia; }
 380 span.gray { color: gray; }
 381 span.green { color: green; }
 382 span.lime { color: lime; }
 383 span.maroon { color: maroon; }
 384 span.navy { color: navy; }
 385 span.olive { color: olive; }
 386 span.purple { color: purple; }
 387 span.red { color: red; }
 388 span.silver { color: silver; }
 389 span.teal { color: teal; }
 390 span.white { color: white; }
 391 span.yellow { color: yellow; }
 392
 393 span.aqua-background { background: aqua; }
 394 span.black-background { background: black; }
 395 span.blue-background { background: blue; }
 396 span.fuchsia-background { background: fuchsia; }
 397 span.gray-background { background: gray; }
 398 span.green-background { background: green; }
 399 span.lime-background { background: lime; }
 400 span.maroon-background { background: maroon; }
 401 span.navy-background { background: navy; }
 402 span.olive-background { background: olive; }
 403 span.purple-background { background: purple; }
 404 span.red-background { background: red; }
 405 span.silver-background { background: silver; }
 406 span.teal-background { background: teal; }
 407 span.white-background { background: white; }
 408 span.yellow-background { background: yellow; }
 409
 410 span.big { font-size: 2em; }
 411 span.small { font-size: 0.6em; }
 412
 413 span.underline { text-decoration: underline; }
 414 span.overline { text-decoration: overline; }
 415 span.line-through { text-decoration: line-through; }
 416
 417 div.unbreakable { page-break-inside: avoid; }
 418
 419
 420 /*
 421  * xhtml11 specific
 422  *
 423  * */
 424
 425 div.tableblock {
 426   margin-top: 1.0em;
 427   margin-bottom: 1.5em;
 428 }
 429 div.tableblock > table {
 430   border: 3px solid #527bbd;
 431 }
 432 thead, p.table.header {
 433   font-weight: bold;
 434   color: #527bbd;
 435 }
 436 p.table {
 437   margin-top: 0;
 438 }
 439 /* Because the table frame attribute is overridden by CSS in most browsers. */
 440 div.tableblock > table[frame="void"] {
 441   border-style: none;
 442 }
 443 div.tableblock > table[frame="hsides"] {
 444   border-left-style: none;
 445   border-right-style: none;
 446 }
 447 div.tableblock > table[frame="vsides"] {
 448   border-top-style: none;
 449   border-bottom-style: none;
 450 }
 451
 452
 453 /*
 454  * html5 specific
 455  *
 456  * */
 457
 458 table.tableblock {
 459   margin-top: 1.0em;
 460   margin-bottom: 1.5em;
 461 }
 462 thead, p.tableblock.header {
 463   font-weight: bold;
 464   color: #527bbd;
 465 }
 466 p.tableblock {
 467   margin-top: 0;
 468 }
 469 table.tableblock {
 470   border-width: 3px;
 471   border-spacing: 0px;
 472   border-style: solid;
 473   border-color: #527bbd;
 474   border-collapse: collapse;
 475 }
 476 th.tableblock, td.tableblock {
 477   border-width: 1px;
 478   padding: 4px;
 479   border-style: solid;
 480   border-color: #527bbd;
 481 }
 482
 483 table.tableblock.frame-topbot {
 484   border-left-style: hidden;
 485   border-right-style: hidden;
 486 }
 487 table.tableblock.frame-sides {
 488   border-top-style: hidden;
 489   border-bottom-style: hidden;
 490 }
 491 table.tableblock.frame-none {
 492   border-style: hidden;
 493 }
 494
 495 th.tableblock.halign-left, td.tableblock.halign-left {
 496   text-align: left;
 497 }
 498 th.tableblock.halign-center, td.tableblock.halign-center {
 499   text-align: center;
 500 }
 501 th.tableblock.halign-right, td.tableblock.halign-right {
 502   text-align: right;
 503 }
 504
 505 th.tableblock.valign-top, td.tableblock.valign-top {
 506   vertical-align: top;
 507 }
 508 th.tableblock.valign-middle, td.tableblock.valign-middle {
 509   vertical-align: middle;
 510 }
 511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
 512   vertical-align: bottom;
 513 }
 514
 515
 516 /*
 517  * manpage specific
 518  *
 519  * */
 520
 521 body.manpage h1 {
 522   padding-top: 0.5em;
 523   padding-bottom: 0.5em;
 524   border-top: 2px solid silver;
 525   border-bottom: 2px solid silver;
 526 }
 527 body.manpage h2 {
 528   border-style: none;
 529 }
 530 body.manpage div.sectionbody {
 531   margin-left: 3em;
 532 }
 533
 534 @media print {
 535   body.manpage div#toc { display: none; }
 536 }
 537
 538
 539 </style>
 540 <script type="text/javascript">
 541 /*<![CDATA[*/
 542 var asciidoc = {  // Namespace.
 543
 544 /////////////////////////////////////////////////////////////////////
 545 // Table Of Contents generator
 546 /////////////////////////////////////////////////////////////////////
 547
 548 /* Author: Mihai Bazon, September 2002
 549  * http://students.infoiasi.ro/~mishoo
 550  *
 551  * Table Of Content generator
 552  * Version: 0.4
 553  *
 554  * Feel free to use this script under the terms of the GNU General Public
 555  * License, as long as you do not remove or alter this notice.
 556  */
 557
 558  /* modified by Troy D. Hanson, September 2006. License: GPL */
 559  /* modified by Stuart Rackham, 2006, 2009. License: GPL */
 560
 561 // toclevels = 1..4.
 562 toc: function (toclevels) {
 563
 564   function getText(el) {
 565     var text = "";
 566     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 567       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 568         text += i.data;
 569       else if (i.firstChild != null)
 570         text += getText(i);
 571     }
 572     return text;
 573   }
 574
 575   function TocEntry(el, text, toclevel) {
 576     this.element = el;
 577     this.text = text;
 578     this.toclevel = toclevel;
 579   }
 580
 581   function tocEntries(el, toclevels) {
 582     var result = new Array;
 583     var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
 584     // Function that scans the DOM tree for header elements (the DOM2
 585     // nodeIterator API would be a better technique but not supported by all
 586     // browsers).
 587     var iterate = function (el) {
 588       for (var i = el.firstChild; i != null; i = i.nextSibling) {
 589         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
 590           var mo = re.exec(i.tagName);
 591           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
 592             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 593           }
 594           iterate(i);
 595         }
 596       }
 597     }
 598     iterate(el);
 599     return result;
 600   }
 601
 602   var toc = document.getElementById("toc");
 603   if (!toc) {
 604     return;
 605   }
 606
 607   // Delete existing TOC entries in case we're reloading the TOC.
 608   var tocEntriesToRemove = [];
 609   var i;
 610   for (i = 0; i < toc.childNodes.length; i++) {
 611     var entry = toc.childNodes[i];
 612     if (entry.nodeName.toLowerCase() == 'div'
 613      && entry.getAttribute("class")
 614      && entry.getAttribute("class").match(/^toclevel/))
 615       tocEntriesToRemove.push(entry);
 616   }
 617   for (i = 0; i < tocEntriesToRemove.length; i++) {
 618     toc.removeChild(tocEntriesToRemove[i]);
 619   }
 620
 621   // Rebuild TOC entries.
 622   var entries = tocEntries(document.getElementById("content"), toclevels);
 623   for (var i = 0; i < entries.length; ++i) {
 624     var entry = entries[i];
 625     if (entry.element.id == "")
 626       entry.element.id = "_toc_" + i;
 627     var a = document.createElement("a");
 628     a.href = "#" + entry.element.id;
 629     a.appendChild(document.createTextNode(entry.text));
 630     var div = document.createElement("div");
 631     div.appendChild(a);
 632     div.className = "toclevel" + entry.toclevel;
 633     toc.appendChild(div);
 634   }
 635   if (entries.length == 0)
 636     toc.parentNode.removeChild(toc);
 637 },
 638
 639
 640 /////////////////////////////////////////////////////////////////////
 641 // Footnotes generator
 642 /////////////////////////////////////////////////////////////////////
 643
 644 /* Based on footnote generation code from:
 645  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 646  */
 647
 648 footnotes: function () {
 649   // Delete existing footnote entries in case we're reloading the footnodes.
 650   var i;
 651   var noteholder = document.getElementById("footnotes");
 652   if (!noteholder) {
 653     return;
 654   }
 655   var entriesToRemove = [];
 656   for (i = 0; i < noteholder.childNodes.length; i++) {
 657     var entry = noteholder.childNodes[i];
 658     if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
 659       entriesToRemove.push(entry);
 660   }
 661   for (i = 0; i < entriesToRemove.length; i++) {
 662     noteholder.removeChild(entriesToRemove[i]);
 663   }
 664
 665   // Rebuild footnote entries.
 666   var cont = document.getElementById("content");
 667   var spans = cont.getElementsByTagName("span");
 668   var refs = {};
 669   var n = 0;
 670   for (i=0; i<spans.length; i++) {
 671     if (spans[i].className == "footnote") {
 672       n++;
 673       var note = spans[i].getAttribute("data-note");
 674       if (!note) {
 675         // Use [\s\S] in place of . so multi-line matches work.
 676         // Because JavaScript has no s (dotall) regex flag.
 677         note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
 678         spans[i].innerHTML =
 679           "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
 680           "' title='View footnote' class='footnote'>" + n + "</a>]";
 681         spans[i].setAttribute("data-note", note);
 682       }
 683       noteholder.innerHTML +=
 684         "<div class='footnote' id='_footnote_" + n + "'>" +
 685         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
 686         n + "</a>. " + note + "</div>";
 687       var id =spans[i].getAttribute("id");
 688       if (id != null) refs["#"+id] = n;
 689     }
 690   }
 691   if (n == 0)
 692     noteholder.parentNode.removeChild(noteholder);
 693   else {
 694     // Process footnoterefs.
 695     for (i=0; i<spans.length; i++) {
 696       if (spans[i].className == "footnoteref") {
 697         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
 698         href = href.match(/#.*/)[0];  // Because IE return full URL.
 699         n = refs[href];
 700         spans[i].innerHTML =
 701           "[<a href='#_footnote_" + n +
 702           "' title='View footnote' class='footnote'>" + n + "</a>]";
 703       }
 704     }
 705   }
 706 },
 707
 708 install: function(toclevels) {
 709   var timerId;
 710
 711   function reinstall() {
 712     asciidoc.footnotes();
 713     if (toclevels) {
 714       asciidoc.toc(toclevels);
 715     }
 716   }
 717
 718   function reinstallAndRemoveTimer() {
 719     clearInterval(timerId);
 720     reinstall();
 721   }
 722
 723   timerId = setInterval(reinstall, 500);
 724   if (document.addEventListener)
 725     document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
 726   else
 727     window.onload = reinstallAndRemoveTimer;
 728 }
 729
 730 }
 731 asciidoc.install();
 732 /*]]>*/
 733 </script>
 734 </head>
 735 <body class="article">
 736 <div id="header">
 737 <h1>Partial Clone Design Notes</h1>
 738 <span id="revdate">2024-01-26</span>
 739 </div>
 740 <div id="content">
 741 <div id="preamble">
 742 <div class="sectionbody">
 743 <div class="paragraph"><p>The "Partial Clone" feature is a performance optimization for Git that
 744 allows Git to function without having a complete copy of the repository.
 745 The goal of this work is to allow Git to better handle extremely large
 746 repositories.</p></div>
 747 <div class="paragraph"><p>During clone and fetch operations, Git downloads the complete contents
 748 and history of the repository.  This includes all commits, trees, and
 749 blobs for the complete life of the repository.  For extremely large
 750 repositories, clones can take hours (or days) and consume 100+GiB of disk
 751 space.</p></div>
 752 <div class="paragraph"><p>Often in these repositories there are many blobs and trees that the user
 753 does not need such as:</p></div>
 754 <div class="olist arabic"><ol class="arabic">
 755 <li>
 756 <p>
 757 files outside of the user&#8217;s work area in the tree.  For example, in
 758      a repository with 500K directories and 3.5M files in every commit,
 759      we can avoid downloading many objects if the user only needs a
 760      narrow "cone" of the source tree.
 761 </p>
 762 </li>
 763 <li>
 764 <p>
 765 large binary assets.  For example, in a repository where large build
 766      artifacts are checked into the tree, we can avoid downloading all
 767      previous versions of these non-mergeable binary assets and only
 768      download versions that are actually referenced.
 769 </p>
 770 </li>
 771 </ol></div>
 772 <div class="paragraph"><p>Partial clone allows us to avoid downloading such unneeded objects <strong>in
 773 advance</strong> during clone and fetch operations and thereby reduce download
 774 times and disk usage.  Missing objects can later be "demand fetched"
 775 if/when needed.</p></div>
 776 <div class="paragraph"><p>A remote that can later provide the missing objects is called a
 777 promisor remote, as it promises to send the objects when
 778 requested. Initially Git supported only one promisor remote, the origin
 779 remote from which the user cloned and that was configured in the
 780 "extensions.partialClone" config option. Later support for more than
 781 one promisor remote has been implemented.</p></div>
 782 <div class="paragraph"><p>Use of partial clone requires that the user be online and the origin
 783 remote or other promisor remotes be available for on-demand fetching
 784 of missing objects.  This may or may not be problematic for the user.
 785 For example, if the user can stay within the pre-selected subset of
 786 the source tree, they may not encounter any missing objects.
 787 Alternatively, the user could try to pre-fetch various objects if they
 788 know that they are going offline.</p></div>
 789 </div>
 790 </div>
 791 <div class="sect1">
 792 <h2 id="_non_goals">Non-Goals</h2>
 793 <div class="sectionbody">
 794 <div class="paragraph"><p>Partial clone is a mechanism to limit the number of blobs and trees downloaded
 795 <strong>within</strong> a given range of commits&#8201;&#8212;&#8201;and is therefore independent of and not
 796 intended to conflict with existing DAG-level mechanisms to limit the set of
 797 requested commits (i.e. shallow clone, single branch, or fetch <em>&lt;refspec&gt;</em>).</p></div>
 798 </div>
 799 </div>
 800 <div class="sect1">
 801 <h2 id="_design_overview">Design Overview</h2>
 802 <div class="sectionbody">
 803 <div class="paragraph"><p>Partial clone logically consists of the following parts:</p></div>
 804 <div class="ulist"><ul>
 805 <li>
 806 <p>
 807 A mechanism for the client to describe unneeded or unwanted objects to
 808   the server.
 809 </p>
 810 </li>
 811 <li>
 812 <p>
 813 A mechanism for the server to omit such unwanted objects from packfiles
 814   sent to the client.
 815 </p>
 816 </li>
 817 <li>
 818 <p>
 819 A mechanism for the client to gracefully handle missing objects (that
 820   were previously omitted by the server).
 821 </p>
 822 </li>
 823 <li>
 824 <p>
 825 A mechanism for the client to backfill missing objects as needed.
 826 </p>
 827 </li>
 828 </ul></div>
 829 </div>
 830 </div>
 831 <div class="sect1">
 832 <h2 id="_design_details">Design Details</h2>
 833 <div class="sectionbody">
 834 <div class="ulist"><ul>
 835 <li>
 836 <p>
 837 A new pack-protocol capability "filter" is added to the fetch-pack and
 838   upload-pack negotiation.
 839 </p>
 840 <div class="paragraph"><p>This uses the existing capability discovery mechanism.
 841 See "filter" in <a href="../gitprotocol-pack.html">gitprotocol-pack(5)</a>.</p></div>
 842 </li>
 843 <li>
 844 <p>
 845 Clients pass a "filter-spec" to clone and fetch which is passed to the
 846   server to request filtering during packfile construction.
 847 </p>
 848 <div class="paragraph"><p>There are various filters available to accommodate different situations.
 849 See "--filter=&lt;filter-spec&gt;" in Documentation/rev-list-options.txt.</p></div>
 850 </li>
 851 <li>
 852 <p>
 853 On the server pack-objects applies the requested filter-spec as it
 854   creates "filtered" packfiles for the client.
 855 </p>
 856 <div class="paragraph"><p>These filtered packfiles are <strong>incomplete</strong> in the traditional sense because
 857 they may contain objects that reference objects not contained in the
 858 packfile and that the client doesn&#8217;t already have.  For example, the
 859 filtered packfile may contain trees or tags that reference missing blobs
 860 or commits that reference missing trees.</p></div>
 861 </li>
 862 <li>
 863 <p>
 864 On the client these incomplete packfiles are marked as "promisor packfiles"
 865   and treated differently by various commands.
 866 </p>
 867 </li>
 868 <li>
 869 <p>
 870 On the client a repository extension is added to the local config to
 871   prevent older versions of git from failing mid-operation because of
 872   missing objects that they cannot handle.
 873   See "extensions.partialClone" in Documentation/technical/repository-version.txt"
 874 </p>
 875 </li>
 876 </ul></div>
 877 </div>
 878 </div>
 879 <div class="sect1">
 880 <h2 id="_handling_missing_objects">Handling Missing Objects</h2>
 881 <div class="sectionbody">
 882 <div class="ulist"><ul>
 883 <li>
 884 <p>
 885 An object may be missing due to a partial clone or fetch, or missing
 886   due to repository corruption.  To differentiate these cases, the
 887   local repository specially indicates such filtered packfiles
 888   obtained from promisor remotes as "promisor packfiles".
 889 </p>
 890 <div class="paragraph"><p>These promisor packfiles consist of a "&lt;name&gt;.promisor" file with
 891 arbitrary contents (like the "&lt;name&gt;.keep" files), in addition to
 892 their "&lt;name&gt;.pack" and "&lt;name&gt;.idx" files.</p></div>
 893 </li>
 894 <li>
 895 <p>
 896 The local repository considers a "promisor object" to be an object that
 897   it knows (to the best of its ability) that promisor remotes have promised
 898   that they have, either because the local repository has that object in one of
 899   its promisor packfiles, or because another promisor object refers to it.
 900 </p>
 901 <div class="paragraph"><p>When Git encounters a missing object, Git can see if it is a promisor object
 902 and handle it appropriately.  If not, Git can report a corruption.</p></div>
 903 <div class="paragraph"><p>This means that there is no need for the client to explicitly maintain an
 904 expensive-to-modify list of missing objects.[a]</p></div>
 905 </li>
 906 <li>
 907 <p>
 908 Since almost all Git code currently expects any referenced object to be
 909   present locally and because we do not want to force every command to do
 910   a dry-run first, a fallback mechanism is added to allow Git to attempt
 911   to dynamically fetch missing objects from promisor remotes.
 912 </p>
 913 <div class="paragraph"><p>When the normal object lookup fails to find an object, Git invokes
 914 promisor_remote_get_direct() to try to get the object from a promisor
 915 remote and then retry the object lookup.  This allows objects to be
 916 "faulted in" without complicated prediction algorithms.</p></div>
 917 <div class="paragraph"><p>For efficiency reasons, no check as to whether the missing object is
 918 actually a promisor object is performed.</p></div>
 919 <div class="paragraph"><p>Dynamic object fetching tends to be slow as objects are fetched one at
 920 a time.</p></div>
 921 </li>
 922 <li>
 923 <p>
 924 <code>checkout</code> (and any other command using <code>unpack-trees</code>) has been taught
 925   to bulk pre-fetch all required missing blobs in a single batch.
 926 </p>
 927 </li>
 928 <li>
 929 <p>
 930 <code>rev-list</code> has been taught to print missing objects.
 931 </p>
 932 <div class="paragraph"><p>This can be used by other commands to bulk prefetch objects.
 933 For example, a "git log -p A..B" may internally want to first do
 934 something like "git rev-list --objects --quiet --missing=print A..B"
 935 and prefetch those objects in bulk.</p></div>
 936 </li>
 937 <li>
 938 <p>
 939 <code>fsck</code> has been updated to be fully aware of promisor objects.
 940 </p>
 941 </li>
 942 <li>
 943 <p>
 944 <code>repack</code> in GC has been updated to not touch promisor packfiles at all,
 945   and to only repack other objects.
 946 </p>
 947 </li>
 948 <li>
 949 <p>
 950 The global variable "fetch_if_missing" is used to control whether an
 951   object lookup will attempt to dynamically fetch a missing object or
 952   report an error.
 953 </p>
 954 <div class="paragraph"><p>We are not happy with this global variable and would like to remove it,
 955 but that requires significant refactoring of the object code to pass an
 956 additional flag.</p></div>
 957 </li>
 958 </ul></div>
 959 </div>
 960 </div>
 961 <div class="sect1">
 962 <h2 id="_fetching_missing_objects">Fetching Missing Objects</h2>
 963 <div class="sectionbody">
 964 <div class="ulist"><ul>
 965 <li>
 966 <p>
 967 Fetching of objects is done by invoking a "git fetch" subprocess.
 968 </p>
 969 </li>
 970 <li>
 971 <p>
 972 The local repository sends a request with the hashes of all requested
 973   objects, and does not perform any packfile negotiation.
 974   It then receives a packfile.
 975 </p>
 976 </li>
 977 <li>
 978 <p>
 979 Because we are reusing the existing fetch mechanism, fetching
 980   currently fetches all objects referred to by the requested objects, even
 981   though they are not necessary.
 982 </p>
 983 </li>
 984 <li>
 985 <p>
 986 Fetching with <code>--refetch</code> will request a complete new filtered packfile from
 987   the remote, which can be used to change a filter without needing to
 988   dynamically fetch missing objects.
 989 </p>
 990 </li>
 991 </ul></div>
 992 </div>
 993 </div>
 994 <div class="sect1">
 995 <h2 id="_using_many_promisor_remotes">Using many promisor remotes</h2>
 996 <div class="sectionbody">
 997 <div class="paragraph"><p>Many promisor remotes can be configured and used.</p></div>
 998 <div class="paragraph"><p>This allows for example a user to have multiple geographically-close
 999 cache servers for fetching missing blobs while continuing to do
1000 filtered <code>git-fetch</code> commands from the central server.</p></div>
1001 <div class="paragraph"><p>When fetching objects, promisor remotes are tried one after the other
1002 until all the objects have been fetched.</p></div>
1003 <div class="paragraph"><p>Remotes that are considered "promisor" remotes are those specified by
1004 the following configuration variables:</p></div>
1005 <div class="ulist"><ul>
1006 <li>
1007 <p>
1008 <code>extensions.partialClone = &lt;name&gt;</code>
1009 </p>
1010 </li>
1011 <li>
1012 <p>
1013 <code>remote.&lt;name&gt;.promisor = true</code>
1014 </p>
1015 </li>
1016 <li>
1017 <p>
1018 <code>remote.&lt;name&gt;.partialCloneFilter = ...</code>
1019 </p>
1020 </li>
1021 </ul></div>
1022 <div class="paragraph"><p>Only one promisor remote can be configured using the
1023 <code>extensions.partialClone</code> config variable. This promisor remote will
1024 be the last one tried when fetching objects.</p></div>
1025 <div class="paragraph"><p>We decided to make it the last one we try, because it is likely that
1026 someone using many promisor remotes is doing so because the other
1027 promisor remotes are better for some reason (maybe they are closer or
1028 faster for some kind of objects) than the origin, and the origin is
1029 likely to be the remote specified by extensions.partialClone.</p></div>
1030 <div class="paragraph"><p>This justification is not very strong, but one choice had to be made,
1031 and anyway the long term plan should be to make the order somehow
1032 fully configurable.</p></div>
1033 <div class="paragraph"><p>For now though the other promisor remotes will be tried in the order
1034 they appear in the config file.</p></div>
1035 </div>
1036 </div>
1037 <div class="sect1">
1038 <h2 id="_current_limitations">Current Limitations</h2>
1039 <div class="sectionbody">
1040 <div class="ulist"><ul>
1041 <li>
1042 <p>
1043 It is not possible to specify the order in which the promisor
1044   remotes are tried in other ways than the order in which they appear
1045   in the config file.
1046 </p>
1047 <div class="paragraph"><p>It is also not possible to specify an order to be used when fetching
1048 from one remote and a different order when fetching from another
1049 remote.</p></div>
1050 </li>
1051 <li>
1052 <p>
1053 It is not possible to push only specific objects to a promisor
1054   remote.
1055 </p>
1056 <div class="paragraph"><p>It is not possible to push at the same time to multiple promisor
1057 remote in a specific order.</p></div>
1058 </li>
1059 <li>
1060 <p>
1061 Dynamic object fetching will only ask promisor remotes for missing
1062   objects.  We assume that promisor remotes have a complete view of the
1063   repository and can satisfy all such requests.
1064 </p>
1065 </li>
1066 <li>
1067 <p>
1068 Repack essentially treats promisor and non-promisor packfiles as 2
1069   distinct partitions and does not mix them.
1070 </p>
1071 </li>
1072 <li>
1073 <p>
1074 Dynamic object fetching invokes fetch-pack once <strong>for each item</strong>
1075   because most algorithms stumble upon a missing object and need to have
1076   it resolved before continuing their work.  This may incur significant
1077   overhead&#8201;&#8212;&#8201;and multiple authentication requests&#8201;&#8212;&#8201;if many objects are
1078   needed.
1079 </p>
1080 </li>
1081 <li>
1082 <p>
1083 Dynamic object fetching currently uses the existing pack protocol V0
1084   which means that each object is requested via fetch-pack.  The server
1085   will send a full set of info/refs when the connection is established.
1086   If there are a large number of refs, this may incur significant overhead.
1087 </p>
1088 </li>
1089 </ul></div>
1090 </div>
1091 </div>
1092 <div class="sect1">
1093 <h2 id="_future_work">Future Work</h2>
1094 <div class="sectionbody">
1095 <div class="ulist"><ul>
1096 <li>
1097 <p>
1098 Improve the way to specify the order in which promisor remotes are
1099   tried.
1100 </p>
1101 <div class="paragraph"><p>For example this could allow specifying explicitly something like:
1102 "When fetching from this remote, I want to use these promisor remotes
1103 in this order, though, when pushing or fetching to that remote, I want
1104 to use those promisor remotes in that order."</p></div>
1105 </li>
1106 <li>
1107 <p>
1108 Allow pushing to promisor remotes.
1109 </p>
1110 <div class="paragraph"><p>The user might want to work in a triangular work flow with multiple
1111 promisor remotes that each have an incomplete view of the repository.</p></div>
1112 </li>
1113 <li>
1114 <p>
1115 Allow non-pathname-based filters to make use of packfile bitmaps (when
1116   present).  This was just an omission during the initial implementation.
1117 </p>
1118 </li>
1119 <li>
1120 <p>
1121 Investigate use of a long-running process to dynamically fetch a series
1122   of objects, such as proposed in [5,6] to reduce process startup and
1123   overhead costs.
1124 </p>
1125 <div class="paragraph"><p>It would be nice if pack protocol V2 could allow that long-running
1126 process to make a series of requests over a single long-running
1127 connection.</p></div>
1128 </li>
1129 <li>
1130 <p>
1131 Investigate pack protocol V2 to avoid the info/refs broadcast on
1132   each connection with the server to dynamically fetch missing objects.
1133 </p>
1134 </li>
1135 <li>
1136 <p>
1137 Investigate the need to handle loose promisor objects.
1138 </p>
1139 <div class="paragraph"><p>Objects in promisor packfiles are allowed to reference missing objects
1140 that can be dynamically fetched from the server.  An assumption was
1141 made that loose objects are only created locally and therefore should
1142 not reference a missing object.  We may need to revisit that assumption
1143 if, for example, we dynamically fetch a missing tree and store it as a
1144 loose object rather than a single object packfile.</p></div>
1145 <div class="paragraph"><p>This does not necessarily mean we need to mark loose objects as promisor;
1146 it may be sufficient to relax the object lookup or is-promisor functions.</p></div>
1147 </li>
1148 </ul></div>
1149 </div>
1150 </div>
1151 <div class="sect1">
1152 <h2 id="_non_tasks">Non-Tasks</h2>
1153 <div class="sectionbody">
1154 <div class="ulist"><ul>
1155 <li>
1156 <p>
1157 Every time the subject of "demand loading blobs" comes up it seems
1158   that someone suggests that the server be allowed to "guess" and send
1159   additional objects that may be related to the requested objects.
1160 </p>
1161 <div class="paragraph"><p>No work has gone into actually doing that; we&#8217;re just documenting that
1162 it is a common suggestion.  We&#8217;re not sure how it would work and have
1163 no plans to work on it.</p></div>
1164 <div class="paragraph"><p>It is valid for the server to send more objects than requested (even
1165 for a dynamic object fetch), but we are not building on that.</p></div>
1166 </li>
1167 </ul></div>
1168 </div>
1169 </div>
1170 <div class="sect1">
1171 <h2 id="_footnotes">Footnotes</h2>
1172 <div class="sectionbody">
1173 <div class="paragraph"><p>[a] expensive-to-modify list of missing objects:  Earlier in the design of
1174     partial clone we discussed the need for a single list of missing objects.
1175     This would essentially be a sorted linear list of OIDs that were
1176     omitted by the server during a clone or subsequent fetches.</p></div>
1177 <div class="paragraph"><p>This file would need to be loaded into memory on every object lookup.
1178 It would need to be read, updated, and re-written (like the .git/index)
1179 on every explicit "git fetch" command <strong>and</strong> on any dynamic object fetch.</p></div>
1180 <div class="paragraph"><p>The cost to read, update, and write this file could add significant
1181 overhead to every command if there are many missing objects.  For example,
1182 if there are 100M missing blobs, this file would be at least 2GiB on disk.</p></div>
1183 <div class="paragraph"><p>With the "promisor" concept, we <strong>infer</strong> a missing object based upon the
1184 type of packfile that references it.</p></div>
1185 </div>
1186 </div>
1187 <div class="sect1">
1188 <h2 id="_related_links">Related Links</h2>
1189 <div class="sectionbody">
1190 <div class="paragraph"><p>[0] <a href="https://crbug.com/git/2">https://crbug.com/git/2</a>
1191     Bug#2: Partial Clone</p></div>
1192 <div class="paragraph"><p>[1] <a href="https://lore.kernel.org/git/20170113155253.1644-1-benpeart@microsoft.com/">https://lore.kernel.org/git/20170113155253.1644-1-benpeart@microsoft.com/</a><br />
1193     Subject: [RFC] Add support for downloading blobs on demand<br />
1194     Date: Fri, 13 Jan 2017 10:52:53 -0500</p></div>
1195 <div class="paragraph"><p>[2] <a href="https://lore.kernel.org/git/cover.1506714999.git.jonathantanmy@google.com/">https://lore.kernel.org/git/cover.1506714999.git.jonathantanmy@google.com/</a><br />
1196     Subject: [PATCH 00/18] Partial clone (from clone to lazy fetch in 18 patches)<br />
1197     Date: Fri, 29 Sep 2017 13:11:36 -0700</p></div>
1198 <div class="paragraph"><p>[3] <a href="https://lore.kernel.org/git/20170426221346.25337-1-jonathantanmy@google.com/">https://lore.kernel.org/git/20170426221346.25337-1-jonathantanmy@google.com/</a><br />
1199     Subject: Proposal for missing blob support in Git repos<br />
1200     Date: Wed, 26 Apr 2017 15:13:46 -0700</p></div>
1201 <div class="paragraph"><p>[4] <a href="https://lore.kernel.org/git/1488999039-37631-1-git-send-email-git@jeffhostetler.com/">https://lore.kernel.org/git/1488999039-37631-1-git-send-email-git@jeffhostetler.com/</a><br />
1202     Subject: [PATCH 00/10] RFC Partial Clone and Fetch<br />
1203     Date: Wed,  8 Mar 2017 18:50:29 +0000</p></div>
1204 <div class="paragraph"><p>[5] <a href="https://lore.kernel.org/git/20170505152802.6724-1-benpeart@microsoft.com/">https://lore.kernel.org/git/20170505152802.6724-1-benpeart@microsoft.com/</a><br />
1205     Subject: [PATCH v7 00/10] refactor the filter process code into a reusable module<br />
1206     Date: Fri,  5 May 2017 11:27:52 -0400</p></div>
1207 <div class="paragraph"><p>[6] <a href="https://lore.kernel.org/git/20170714132651.170708-1-benpeart@microsoft.com/">https://lore.kernel.org/git/20170714132651.170708-1-benpeart@microsoft.com/</a><br />
1208     Subject: [RFC/PATCH v2 0/1] Add support for downloading blobs on demand<br />
1209     Date: Fri, 14 Jul 2017 09:26:50 -0400</p></div>
1210 </div>
1211 </div>
1212 </div>
1213 <div id="footnotes"><hr /></div>
1214 <div id="footer">
1215 <div id="footer-text">
1216 Last updated
1217  2023-10-23 14:43:46 PDT
1218 </div>
1219 </div>
1220 </body>
1221 </html>