gitprotocol-v2.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>gitprotocol-v2(5)</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="manpage">
 736 <div id="header">
 737 <h1>
 738 gitprotocol-v2(5) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>gitprotocol-v2 -
 743    Git Wire Protocol, Version 2
 744 </p>
 745 </div>
 746 </div>
 747 <div id="content">
 748 <div class="sect1">
 749 <h2 id="_synopsis">SYNOPSIS</h2>
 750 <div class="sectionbody">
 751 <div class="verseblock">
 752 <pre class="content">&lt;over-the-wire-protocol&gt;</pre>
 753 <div class="attribution">
 754 </div></div>
 755 </div>
 756 </div>
 757 <div class="sect1">
 758 <h2 id="_description">DESCRIPTION</h2>
 759 <div class="sectionbody">
 760 <div class="paragraph"><p>This document presents a specification for a version 2 of Git&#8217;s wire
 761 protocol.  Protocol v2 will improve upon v1 in the following ways:</p></div>
 762 <div class="ulist"><ul>
 763 <li>
 764 <p>
 765 Instead of multiple service names, multiple commands will be
 766     supported by a single service
 767 </p>
 768 </li>
 769 <li>
 770 <p>
 771 Easily extendable as capabilities are moved into their own section
 772     of the protocol, no longer being hidden behind a NUL byte and
 773     limited by the size of a pkt-line
 774 </p>
 775 </li>
 776 <li>
 777 <p>
 778 Separate out other information hidden behind NUL bytes (e.g. agent
 779     string as a capability and symrefs can be requested using <em>ls-refs</em>)
 780 </p>
 781 </li>
 782 <li>
 783 <p>
 784 Reference advertisement will be omitted unless explicitly requested
 785 </p>
 786 </li>
 787 <li>
 788 <p>
 789 ls-refs command to explicitly request some refs
 790 </p>
 791 </li>
 792 <li>
 793 <p>
 794 Designed with http and stateless-rpc in mind.  With clear flush
 795     semantics the http remote helper can simply act as a proxy
 796 </p>
 797 </li>
 798 </ul></div>
 799 <div class="paragraph"><p>In protocol v2 communication is command oriented.  When first contacting a
 800 server a list of capabilities will be advertised.  Some of these capabilities
 801 will be commands which a client can request be executed.  Once a command
 802 has completed, a client can reuse the connection and request that other
 803 commands be executed.</p></div>
 804 </div>
 805 </div>
 806 <div class="sect1">
 807 <h2 id="_packet_line_framing">Packet-Line Framing</h2>
 808 <div class="sectionbody">
 809 <div class="paragraph"><p>All communication is done using packet-line framing, just as in v1.  See
 810 <a href="gitprotocol-pack.html">gitprotocol-pack(5)</a> and <a href="gitprotocol-common.html">gitprotocol-common(5)</a> for more information.</p></div>
 811 <div class="paragraph"><p>In protocol v2 these special packets will have the following semantics:</p></div>
 812 <div class="ulist"><ul>
 813 <li>
 814 <p>
 815 <em>0000</em> Flush Packet (flush-pkt) - indicates the end of a message
 816 </p>
 817 </li>
 818 <li>
 819 <p>
 820 <em>0001</em> Delimiter Packet (delim-pkt) - separates sections of a message
 821 </p>
 822 </li>
 823 <li>
 824 <p>
 825 <em>0002</em> Response End Packet (response-end-pkt) - indicates the end of a
 826     response for stateless connections
 827 </p>
 828 </li>
 829 </ul></div>
 830 </div>
 831 </div>
 832 <div class="sect1">
 833 <h2 id="_initial_client_request">Initial Client Request</h2>
 834 <div class="sectionbody">
 835 <div class="paragraph"><p>In general a client can request to speak protocol v2 by sending
 836 <code>version=2</code> through the respective side-channel for the transport being
 837 used which inevitably sets <code>GIT_PROTOCOL</code>.  More information can be
 838 found in <a href="gitprotocol-pack.html">gitprotocol-pack(5)</a> and <a href="gitprotocol-http.html">gitprotocol-http(5)</a>, as well as the
 839 <code>GIT_PROTOCOL</code> definition in <code>git.txt</code>. In all cases the
 840 response from the server is the capability advertisement.</p></div>
 841 <div class="sect2">
 842 <h3 id="_git_transport">Git Transport</h3>
 843 <div class="paragraph"><p>When using the git:// transport, you can request to use protocol v2 by
 844 sending "version=2" as an extra parameter:</p></div>
 845 <div class="literalblock">
 846 <div class="content">
 847 <pre><code>003egit-upload-pack /project.git\0host=myserver.com\0\0version=2\0</code></pre>
 848 </div></div>
 849 </div>
 850 <div class="sect2">
 851 <h3 id="_ssh_and_file_transport">SSH and File Transport</h3>
 852 <div class="paragraph"><p>When using either the ssh:// or file:// transport, the GIT_PROTOCOL
 853 environment variable must be set explicitly to include "version=2".
 854 The server may need to be configured to allow this environment variable
 855 to pass.</p></div>
 856 </div>
 857 <div class="sect2">
 858 <h3 id="_http_transport">HTTP Transport</h3>
 859 <div class="paragraph"><p>When using the http:// or https:// transport a client makes a "smart"
 860 info/refs request as described in <a href="gitprotocol-http.html">gitprotocol-http(5)</a> and requests that
 861 v2 be used by supplying "version=2" in the <code>Git-Protocol</code> header.</p></div>
 862 <div class="literalblock">
 863 <div class="content">
 864 <pre><code>C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0
 865 C: Git-Protocol: version=2</code></pre>
 866 </div></div>
 867 <div class="paragraph"><p>A v2 server would reply:</p></div>
 868 <div class="literalblock">
 869 <div class="content">
 870 <pre><code>S: 200 OK
 871 S: &lt;Some headers&gt;
 872 S: ...
 873 S:
 874 S: 000eversion 2\n
 875 S: &lt;capability-advertisement&gt;</code></pre>
 876 </div></div>
 877 <div class="paragraph"><p>Subsequent requests are then made directly to the service
 878 <code>$GIT_URL/git-upload-pack</code>. (This works the same for git-receive-pack).</p></div>
 879 <div class="paragraph"><p>Uses the <code>--http-backend-info-refs</code> option to
 880 <a href="git-upload-pack.html">git-upload-pack(1)</a>.</p></div>
 881 <div class="paragraph"><p>The server may need to be configured to pass this header&#8217;s contents via
 882 the <code>GIT_PROTOCOL</code> variable. See the discussion in <code>git-http-backend.txt</code>.</p></div>
 883 </div>
 884 </div>
 885 </div>
 886 <div class="sect1">
 887 <h2 id="_capability_advertisement">Capability Advertisement</h2>
 888 <div class="sectionbody">
 889 <div class="paragraph"><p>A server which decides to communicate (based on a request from a client)
 890 using protocol version 2, notifies the client by sending a version string
 891 in its initial response followed by an advertisement of its capabilities.
 892 Each capability is a key with an optional value.  Clients must ignore all
 893 unknown keys.  Semantics of unknown values are left to the definition of
 894 each key.  Some capabilities will describe commands which can be requested
 895 to be executed by the client.</p></div>
 896 <div class="literalblock">
 897 <div class="content">
 898 <pre><code>capability-advertisement = protocol-version
 899                            capability-list
 900                            flush-pkt</code></pre>
 901 </div></div>
 902 <div class="literalblock">
 903 <div class="content">
 904 <pre><code>protocol-version = PKT-LINE("version 2" LF)
 905 capability-list = *capability
 906 capability = PKT-LINE(key[=value] LF)</code></pre>
 907 </div></div>
 908 <div class="literalblock">
 909 <div class="content">
 910 <pre><code>key = 1*(ALPHA | DIGIT | "-_")
 911 value = 1*(ALPHA | DIGIT | " -_.,?\/{}[]()&lt;&gt;!@#$%^&amp;*+=:;")</code></pre>
 912 </div></div>
 913 </div>
 914 </div>
 915 <div class="sect1">
 916 <h2 id="_command_request">Command Request</h2>
 917 <div class="sectionbody">
 918 <div class="paragraph"><p>After receiving the capability advertisement, a client can then issue a
 919 request to select the command it wants with any particular capabilities
 920 or arguments.  There is then an optional section where the client can
 921 provide any command specific parameters or queries.  Only a single
 922 command can be requested at a time.</p></div>
 923 <div class="literalblock">
 924 <div class="content">
 925 <pre><code>request = empty-request | command-request
 926 empty-request = flush-pkt
 927 command-request = command
 928                   capability-list
 929                   delim-pkt
 930                   command-args
 931                   flush-pkt
 932 command = PKT-LINE("command=" key LF)
 933 command-args = *command-specific-arg</code></pre>
 934 </div></div>
 935 <div class="literalblock">
 936 <div class="content">
 937 <pre><code>command-specific-args are packet line framed arguments defined by
 938 each individual command.</code></pre>
 939 </div></div>
 940 <div class="paragraph"><p>The server will then check to ensure that the client&#8217;s request is
 941 comprised of a valid command as well as valid capabilities which were
 942 advertised.  If the request is valid the server will then execute the
 943 command.  A server MUST wait till it has received the client&#8217;s entire
 944 request before issuing a response.  The format of the response is
 945 determined by the command being executed, but in all cases a flush-pkt
 946 indicates the end of the response.</p></div>
 947 <div class="paragraph"><p>When a command has finished, and the client has received the entire
 948 response from the server, a client can either request that another
 949 command be executed or can terminate the connection.  A client may
 950 optionally send an empty request consisting of just a flush-pkt to
 951 indicate that no more requests will be made.</p></div>
 952 </div>
 953 </div>
 954 <div class="sect1">
 955 <h2 id="_capabilities">Capabilities</h2>
 956 <div class="sectionbody">
 957 <div class="paragraph"><p>There are two different types of capabilities: normal capabilities,
 958 which can be used to convey information or alter the behavior of a
 959 request, and commands, which are the core actions that a client wants to
 960 perform (fetch, push, etc).</p></div>
 961 <div class="paragraph"><p>Protocol version 2 is stateless by default.  This means that all commands
 962 must only last a single round and be stateless from the perspective of the
 963 server side, unless the client has requested a capability indicating that
 964 state should be maintained by the server.  Clients MUST NOT require state
 965 management on the server side in order to function correctly.  This
 966 permits simple round-robin load-balancing on the server side, without
 967 needing to worry about state management.</p></div>
 968 <div class="sect2">
 969 <h3 id="_agent">agent</h3>
 970 <div class="paragraph"><p>The server can advertise the <code>agent</code> capability with a value <code>X</code> (in the
 971 form <code>agent=X</code>) to notify the client that the server is running version
 972 <code>X</code>.  The client may optionally send its own agent string by including
 973 the <code>agent</code> capability with a value <code>Y</code> (in the form <code>agent=Y</code>) in its
 974 request to the server (but it MUST NOT do so if the server did not
 975 advertise the agent capability). The <code>X</code> and <code>Y</code> strings may contain any
 976 printable ASCII characters except space (i.e., the byte range 32 &lt; x &lt;
 977 127), and are typically of the form "package/version" (e.g.,
 978 "git/1.8.3.1"). The agent strings are purely informative for statistics
 979 and debugging purposes, and MUST NOT be used to programmatically assume
 980 the presence or absence of particular features.</p></div>
 981 </div>
 982 <div class="sect2">
 983 <h3 id="_ls_refs">ls-refs</h3>
 984 <div class="paragraph"><p><code>ls-refs</code> is the command used to request a reference advertisement in v2.
 985 Unlike the current reference advertisement, ls-refs takes in arguments
 986 which can be used to limit the refs sent from the server.</p></div>
 987 <div class="paragraph"><p>Additional features not supported in the base command will be advertised
 988 as the value of the command in the capability advertisement in the form
 989 of a space separated list of features: "&lt;command&gt;=&lt;feature-1&gt; &lt;feature-2&gt;"</p></div>
 990 <div class="paragraph"><p>ls-refs takes in the following arguments:</p></div>
 991 <div class="literalblock">
 992 <div class="content">
 993 <pre><code>symrefs
 994     In addition to the object pointed by it, show the underlying ref
 995     pointed by it when showing a symbolic ref.
 996 peel
 997     Show peeled tags.
 998 ref-prefix &lt;prefix&gt;
 999     When specified, only references having a prefix matching one of
1000     the provided prefixes are displayed. Multiple instances may be
1001     given, in which case references matching any prefix will be
1002     shown. Note that this is purely for optimization; a server MAY
1003     show refs not matching the prefix if it chooses, and clients
1004     should filter the result themselves.</code></pre>
1005 </div></div>
1006 <div class="paragraph"><p>If the <em>unborn</em> feature is advertised the following argument can be
1007 included in the client&#8217;s request.</p></div>
1008 <div class="literalblock">
1009 <div class="content">
1010 <pre><code>unborn
1011     The server will send information about HEAD even if it is a symref
1012     pointing to an unborn branch in the form "unborn HEAD
1013     symref-target:&lt;target&gt;".</code></pre>
1014 </div></div>
1015 <div class="paragraph"><p>The output of ls-refs is as follows:</p></div>
1016 <div class="literalblock">
1017 <div class="content">
1018 <pre><code>output = *ref
1019          flush-pkt
1020 obj-id-or-unborn = (obj-id | "unborn")
1021 ref = PKT-LINE(obj-id-or-unborn SP refname *(SP ref-attribute) LF)
1022 ref-attribute = (symref | peeled)
1023 symref = "symref-target:" symref-target
1024 peeled = "peeled:" obj-id</code></pre>
1025 </div></div>
1026 </div>
1027 <div class="sect2">
1028 <h3 id="_fetch">fetch</h3>
1029 <div class="paragraph"><p><code>fetch</code> is the command used to fetch a packfile in v2.  It can be looked
1030 at as a modified version of the v1 fetch where the ref-advertisement is
1031 stripped out (since the <code>ls-refs</code> command fills that role) and the
1032 message format is tweaked to eliminate redundancies and permit easy
1033 addition of future extensions.</p></div>
1034 <div class="paragraph"><p>Additional features not supported in the base command will be advertised
1035 as the value of the command in the capability advertisement in the form
1036 of a space separated list of features: "&lt;command&gt;=&lt;feature-1&gt; &lt;feature-2&gt;"</p></div>
1037 <div class="paragraph"><p>A <code>fetch</code> request can take the following arguments:</p></div>
1038 <div class="literalblock">
1039 <div class="content">
1040 <pre><code>want &lt;oid&gt;
1041     Indicates to the server an object which the client wants to
1042     retrieve.  Wants can be anything and are not limited to
1043     advertised objects.</code></pre>
1044 </div></div>
1045 <div class="literalblock">
1046 <div class="content">
1047 <pre><code>have &lt;oid&gt;
1048     Indicates to the server an object which the client has locally.
1049     This allows the server to make a packfile which only contains
1050     the objects that the client needs. Multiple 'have' lines can be
1051     supplied.</code></pre>
1052 </div></div>
1053 <div class="literalblock">
1054 <div class="content">
1055 <pre><code>done
1056     Indicates to the server that negotiation should terminate (or
1057     not even begin if performing a clone) and that the server should
1058     use the information supplied in the request to construct the
1059     packfile.</code></pre>
1060 </div></div>
1061 <div class="literalblock">
1062 <div class="content">
1063 <pre><code>thin-pack
1064     Request that a thin pack be sent, which is a pack with deltas
1065     which reference base objects not contained within the pack (but
1066     are known to exist at the receiving end). This can reduce the
1067     network traffic significantly, but it requires the receiving end
1068     to know how to "thicken" these packs by adding the missing bases
1069     to the pack.</code></pre>
1070 </div></div>
1071 <div class="literalblock">
1072 <div class="content">
1073 <pre><code>no-progress
1074     Request that progress information that would normally be sent on
1075     side-band channel 2, during the packfile transfer, should not be
1076     sent.  However, the side-band channel 3 is still used for error
1077     responses.</code></pre>
1078 </div></div>
1079 <div class="literalblock">
1080 <div class="content">
1081 <pre><code>include-tag
1082     Request that annotated tags should be sent if the objects they
1083     point to are being sent.</code></pre>
1084 </div></div>
1085 <div class="literalblock">
1086 <div class="content">
1087 <pre><code>ofs-delta
1088     Indicate that the client understands PACKv2 with delta referring
1089     to its base by position in pack rather than by an oid.  That is,
1090     they can read OBJ_OFS_DELTA (aka type 6) in a packfile.</code></pre>
1091 </div></div>
1092 <div class="paragraph"><p>If the <em>shallow</em> feature is advertised the following arguments can be
1093 included in the clients request as well as the potential addition of the
1094 <em>shallow-info</em> section in the server&#8217;s response as explained below.</p></div>
1095 <div class="literalblock">
1096 <div class="content">
1097 <pre><code>shallow &lt;oid&gt;
1098     A client must notify the server of all commits for which it only
1099     has shallow copies (meaning that it doesn't have the parents of
1100     a commit) by supplying a 'shallow &lt;oid&gt;' line for each such
1101     object so that the server is aware of the limitations of the
1102     client's history.  This is so that the server is aware that the
1103     client may not have all objects reachable from such commits.</code></pre>
1104 </div></div>
1105 <div class="literalblock">
1106 <div class="content">
1107 <pre><code>deepen &lt;depth&gt;
1108     Requests that the fetch/clone should be shallow having a commit
1109     depth of &lt;depth&gt; relative to the remote side.</code></pre>
1110 </div></div>
1111 <div class="literalblock">
1112 <div class="content">
1113 <pre><code>deepen-relative
1114     Requests that the semantics of the "deepen" command be changed
1115     to indicate that the depth requested is relative to the client's
1116     current shallow boundary, instead of relative to the requested
1117     commits.</code></pre>
1118 </div></div>
1119 <div class="literalblock">
1120 <div class="content">
1121 <pre><code>deepen-since &lt;timestamp&gt;
1122     Requests that the shallow clone/fetch should be cut at a
1123     specific time, instead of depth.  Internally it's equivalent to
1124     doing "git rev-list --max-age=&lt;timestamp&gt;". Cannot be used with
1125     "deepen".</code></pre>
1126 </div></div>
1127 <div class="literalblock">
1128 <div class="content">
1129 <pre><code>deepen-not &lt;rev&gt;
1130     Requests that the shallow clone/fetch should be cut at a
1131     specific revision specified by '&lt;rev&gt;', instead of a depth.
1132     Internally it's equivalent of doing "git rev-list --not &lt;rev&gt;".
1133     Cannot be used with "deepen", but can be used with
1134     "deepen-since".</code></pre>
1135 </div></div>
1136 <div class="paragraph"><p>If the <em>filter</em> feature is advertised, the following argument can be
1137 included in the client&#8217;s request:</p></div>
1138 <div class="literalblock">
1139 <div class="content">
1140 <pre><code>filter &lt;filter-spec&gt;
1141     Request that various objects from the packfile be omitted
1142     using one of several filtering techniques. These are intended
1143     for use with partial clone and partial fetch operations. See
1144     `rev-list` for possible "filter-spec" values. When communicating
1145     with other processes, senders SHOULD translate scaled integers
1146     (e.g. "1k") into a fully-expanded form (e.g. "1024") to aid
1147     interoperability with older receivers that may not understand
1148     newly-invented scaling suffixes. However, receivers SHOULD
1149     accept the following suffixes: 'k', 'm', and 'g' for 1024,
1150     1048576, and 1073741824, respectively.</code></pre>
1151 </div></div>
1152 <div class="paragraph"><p>If the <em>ref-in-want</em> feature is advertised, the following argument can
1153 be included in the client&#8217;s request as well as the potential addition of
1154 the <em>wanted-refs</em> section in the server&#8217;s response as explained below.</p></div>
1155 <div class="literalblock">
1156 <div class="content">
1157 <pre><code>want-ref &lt;ref&gt;
1158     Indicates to the server that the client wants to retrieve a
1159     particular ref, where &lt;ref&gt; is the full name of a ref on the
1160     server.  It is a protocol error to send want-ref for the
1161     same ref more than once.</code></pre>
1162 </div></div>
1163 <div class="paragraph"><p>If the <em>sideband-all</em> feature is advertised, the following argument can be
1164 included in the client&#8217;s request:</p></div>
1165 <div class="literalblock">
1166 <div class="content">
1167 <pre><code>sideband-all
1168     Instruct the server to send the whole response multiplexed, not just
1169     the packfile section. All non-flush and non-delim PKT-LINE in the
1170     response (not only in the packfile section) will then start with a byte
1171     indicating its sideband (1, 2, or 3), and the server may send "0005\2"
1172     (a PKT-LINE of sideband 2 with no payload) as a keepalive packet.</code></pre>
1173 </div></div>
1174 <div class="paragraph"><p>If the <em>packfile-uris</em> feature is advertised, the following argument
1175 can be included in the client&#8217;s request as well as the potential
1176 addition of the <em>packfile-uris</em> section in the server&#8217;s response as
1177 explained below. Note that at most one <code>packfile-uris</code> line can be sent
1178 to the server.</p></div>
1179 <div class="literalblock">
1180 <div class="content">
1181 <pre><code>packfile-uris &lt;comma-separated-list-of-protocols&gt;
1182     Indicates to the server that the client is willing to receive
1183     URIs of any of the given protocols in place of objects in the
1184     sent packfile. Before performing the connectivity check, the
1185     client should download from all given URIs. Currently, the
1186     protocols supported are "http" and "https".</code></pre>
1187 </div></div>
1188 <div class="paragraph"><p>If the <em>wait-for-done</em> feature is advertised, the following argument
1189 can be included in the client&#8217;s request.</p></div>
1190 <div class="literalblock">
1191 <div class="content">
1192 <pre><code>wait-for-done
1193     Indicates to the server that it should never send "ready", but
1194     should wait for the client to say "done" before sending the
1195     packfile.</code></pre>
1196 </div></div>
1197 <div class="paragraph"><p>The response of <code>fetch</code> is broken into a number of sections separated by
1198 delimiter packets (0001), with each section beginning with its section
1199 header. Most sections are sent only when the packfile is sent.</p></div>
1200 <div class="literalblock">
1201 <div class="content">
1202 <pre><code>output = acknowledgements flush-pkt |
1203          [acknowledgments delim-pkt] [shallow-info delim-pkt]
1204          [wanted-refs delim-pkt] [packfile-uris delim-pkt]
1205          packfile flush-pkt</code></pre>
1206 </div></div>
1207 <div class="literalblock">
1208 <div class="content">
1209 <pre><code>acknowledgments = PKT-LINE("acknowledgments" LF)
1210                   (nak | *ack)
1211                   (ready)
1212 ready = PKT-LINE("ready" LF)
1213 nak = PKT-LINE("NAK" LF)
1214 ack = PKT-LINE("ACK" SP obj-id LF)</code></pre>
1215 </div></div>
1216 <div class="literalblock">
1217 <div class="content">
1218 <pre><code>shallow-info = PKT-LINE("shallow-info" LF)
1219                *PKT-LINE((shallow | unshallow) LF)
1220 shallow = "shallow" SP obj-id
1221 unshallow = "unshallow" SP obj-id</code></pre>
1222 </div></div>
1223 <div class="literalblock">
1224 <div class="content">
1225 <pre><code>wanted-refs = PKT-LINE("wanted-refs" LF)
1226               *PKT-LINE(wanted-ref LF)
1227 wanted-ref = obj-id SP refname</code></pre>
1228 </div></div>
1229 <div class="literalblock">
1230 <div class="content">
1231 <pre><code>packfile-uris = PKT-LINE("packfile-uris" LF) *packfile-uri
1232 packfile-uri = PKT-LINE(40*(HEXDIGIT) SP *%x20-ff LF)</code></pre>
1233 </div></div>
1234 <div class="literalblock">
1235 <div class="content">
1236 <pre><code>packfile = PKT-LINE("packfile" LF)
1237            *PKT-LINE(%x01-03 *%x00-ff)</code></pre>
1238 </div></div>
1239 <div class="literalblock">
1240 <div class="content">
1241 <pre><code>acknowledgments section
1242     * If the client determines that it is finished with negotiations by
1243       sending a "done" line (thus requiring the server to send a packfile),
1244       the acknowledgments sections MUST be omitted from the server's
1245       response.</code></pre>
1246 </div></div>
1247 <div class="ulist"><ul>
1248 <li>
1249 <p>
1250 Always begins with the section header "acknowledgments"
1251 </p>
1252 </li>
1253 <li>
1254 <p>
1255 The server will respond with "NAK" if none of the object ids sent
1256           as have lines were common.
1257 </p>
1258 </li>
1259 <li>
1260 <p>
1261 The server will respond with "ACK obj-id" for all of the
1262           object ids sent as have lines which are common.
1263 </p>
1264 </li>
1265 <li>
1266 <p>
1267 A response cannot have both "ACK" lines as well as a "NAK"
1268           line.
1269 </p>
1270 </li>
1271 <li>
1272 <p>
1273 The server will respond with a "ready" line indicating that
1274           the server has found an acceptable common base and is ready to
1275           make and send a packfile (which will be found in the packfile
1276           section of the same response)
1277 </p>
1278 </li>
1279 <li>
1280 <p>
1281 If the server has found a suitable cut point and has decided
1282           to send a "ready" line, then the server can decide to (as an
1283           optimization) omit any "ACK" lines it would have sent during
1284           its response.  This is because the server will have already
1285           determined the objects it plans to send to the client and no
1286           further negotiation is needed.
1287 </p>
1288 <div class="literalblock">
1289 <div class="content">
1290 <pre><code>shallow-info section
1291     * If the client has requested a shallow fetch/clone, a shallow
1292       client requests a fetch or the server is shallow then the
1293       server's response may include a shallow-info section.  The
1294       shallow-info section will be included if (due to one of the
1295       above conditions) the server needs to inform the client of any
1296       shallow boundaries or adjustments to the clients already
1297       existing shallow boundaries.</code></pre>
1298 </div></div>
1299 </li>
1300 <li>
1301 <p>
1302 Always begins with the section header "shallow-info"
1303 </p>
1304 </li>
1305 <li>
1306 <p>
1307 If a positive depth is requested, the server will compute the
1308           set of commits which are no deeper than the desired depth.
1309 </p>
1310 </li>
1311 <li>
1312 <p>
1313 The server sends a "shallow obj-id" line for each commit whose
1314           parents will not be sent in the following packfile.
1315 </p>
1316 </li>
1317 <li>
1318 <p>
1319 The server sends an "unshallow obj-id" line for each commit
1320           which the client has indicated is shallow, but is no longer
1321           shallow as a result of the fetch (due to its parents being
1322           sent in the following packfile).
1323 </p>
1324 </li>
1325 <li>
1326 <p>
1327 The server MUST NOT send any "unshallow" lines for anything
1328           which the client has not indicated was shallow as a part of
1329           its request.
1330 </p>
1331 <div class="literalblock">
1332 <div class="content">
1333 <pre><code>wanted-refs section
1334     * This section is only included if the client has requested a
1335       ref using a 'want-ref' line and if a packfile section is also
1336       included in the response.</code></pre>
1337 </div></div>
1338 </li>
1339 <li>
1340 <p>
1341 Always begins with the section header "wanted-refs".
1342 </p>
1343 </li>
1344 <li>
1345 <p>
1346 The server will send a ref listing ("&lt;oid&gt; &lt;refname&gt;") for
1347           each reference requested using <em>want-ref</em> lines.
1348 </p>
1349 </li>
1350 <li>
1351 <p>
1352 The server MUST NOT send any refs which were not requested
1353           using <em>want-ref</em> lines.
1354 </p>
1355 <div class="literalblock">
1356 <div class="content">
1357 <pre><code>packfile-uris section
1358     * This section is only included if the client sent
1359       'packfile-uris' and the server has at least one such URI to
1360       send.</code></pre>
1361 </div></div>
1362 </li>
1363 <li>
1364 <p>
1365 Always begins with the section header "packfile-uris".
1366 </p>
1367 </li>
1368 <li>
1369 <p>
1370 For each URI the server sends, it sends a hash of the pack&#8217;s
1371           contents (as output by git index-pack) followed by the URI.
1372 </p>
1373 </li>
1374 <li>
1375 <p>
1376 The hashes are 40 hex characters long. When Git upgrades to a new
1377           hash algorithm, this might need to be updated. (It should match
1378           whatever index-pack outputs after "pack\t" or "keep\t".
1379 </p>
1380 <div class="literalblock">
1381 <div class="content">
1382 <pre><code>packfile section
1383     * This section is only included if the client has sent 'want'
1384       lines in its request and either requested that no more
1385       negotiation be done by sending 'done' or if the server has
1386       decided it has found a sufficient cut point to produce a
1387       packfile.</code></pre>
1388 </div></div>
1389 </li>
1390 <li>
1391 <p>
1392 Always begins with the section header "packfile"
1393 </p>
1394 </li>
1395 <li>
1396 <p>
1397 The transmission of the packfile begins immediately after the
1398           section header
1399 </p>
1400 </li>
1401 <li>
1402 <p>
1403 The data transfer of the packfile is always multiplexed, using
1404           the same semantics of the <em>side-band-64k</em> capability from
1405           protocol version 1.  This means that each packet, during the
1406           packfile data stream, is made up of a leading 4-byte pkt-line
1407           length (typical of the pkt-line format), followed by a 1-byte
1408           stream code, followed by the actual data.
1409 </p>
1410 <div class="literalblock">
1411 <div class="content">
1412 <pre><code>The stream code can be one of:
1413       1 - pack data
1414       2 - progress messages
1415       3 - fatal error message just before stream aborts</code></pre>
1416 </div></div>
1417 </li>
1418 </ul></div>
1419 </div>
1420 <div class="sect2">
1421 <h3 id="_server_option">server-option</h3>
1422 <div class="paragraph"><p>If advertised, indicates that any number of server specific options can be
1423 included in a request.  This is done by sending each option as a
1424 "server-option=&lt;option&gt;" capability line in the capability-list section of
1425 a request.</p></div>
1426 <div class="paragraph"><p>The provided options must not contain a NUL or LF character.</p></div>
1427 </div>
1428 <div class="sect2">
1429 <h3 id="_object_format"> object-format</h3>
1430 <div class="paragraph"><p>The server can advertise the <code>object-format</code> capability with a value <code>X</code> (in the
1431 form <code>object-format=X</code>) to notify the client that the server is able to deal
1432 with objects using hash algorithm X.  If not specified, the server is assumed to
1433 only handle SHA-1.  If the client would like to use a hash algorithm other than
1434 SHA-1, it should specify its object-format string.</p></div>
1435 </div>
1436 <div class="sect2">
1437 <h3 id="_session_id_lt_session_id_gt">session-id=&lt;session-id&gt;</h3>
1438 <div class="paragraph"><p>The server may advertise a session ID that can be used to identify this process
1439 across multiple requests. The client may advertise its own session ID back to
1440 the server as well.</p></div>
1441 <div class="paragraph"><p>Session IDs should be unique to a given process. They must fit within a
1442 packet-line, and must not contain non-printable or whitespace characters. The
1443 current implementation uses trace2 session IDs (see
1444 <a href="technical/api-trace2.html">api-trace2</a> for details), but this may change
1445 and users of the session ID should not rely on this fact.</p></div>
1446 </div>
1447 <div class="sect2">
1448 <h3 id="_object_info">object-info</h3>
1449 <div class="paragraph"><p><code>object-info</code> is the command to retrieve information about one or more objects.
1450 Its main purpose is to allow a client to make decisions based on this
1451 information without having to fully fetch objects. Object size is the only
1452 information that is currently supported.</p></div>
1453 <div class="paragraph"><p>An <code>object-info</code> request takes the following arguments:</p></div>
1454 <div class="literalblock">
1455 <div class="content">
1456 <pre><code>size
1457 Requests size information to be returned for each listed object id.</code></pre>
1458 </div></div>
1459 <div class="literalblock">
1460 <div class="content">
1461 <pre><code>oid &lt;oid&gt;
1462 Indicates to the server an object which the client wants to obtain
1463 information for.</code></pre>
1464 </div></div>
1465 <div class="paragraph"><p>The response of <code>object-info</code> is a list of the requested object ids
1466 and associated requested information, each separated by a single space.</p></div>
1467 <div class="literalblock">
1468 <div class="content">
1469 <pre><code>output = info flush-pkt</code></pre>
1470 </div></div>
1471 <div class="literalblock">
1472 <div class="content">
1473 <pre><code>info = PKT-LINE(attrs) LF)
1474         *PKT-LINE(obj-info LF)</code></pre>
1475 </div></div>
1476 <div class="literalblock">
1477 <div class="content">
1478 <pre><code>attrs = attr | attrs SP attrs</code></pre>
1479 </div></div>
1480 <div class="literalblock">
1481 <div class="content">
1482 <pre><code>attr = "size"</code></pre>
1483 </div></div>
1484 <div class="literalblock">
1485 <div class="content">
1486 <pre><code>obj-info = obj-id SP obj-size</code></pre>
1487 </div></div>
1488 </div>
1489 <div class="sect2">
1490 <h3 id="_bundle_uri">bundle-uri</h3>
1491 <div class="paragraph"><p>If the <em>bundle-uri</em> capability is advertised, the server supports the
1492 &#8216;bundle-uri&#8217; command.</p></div>
1493 <div class="paragraph"><p>The capability is currently advertised with no value (i.e. not
1494 "bundle-uri=somevalue"), a value may be added in the future for
1495 supporting command-wide extensions. Clients MUST ignore any unknown
1496 capability values and proceed with the 'bundle-uri` dialog they
1497 support.</p></div>
1498 <div class="paragraph"><p>The <em>bundle-uri</em> command is intended to be issued before <code>fetch</code> to
1499 get URIs to bundle files (see <a href="git-bundle.html">git-bundle(1)</a>) to "seed" and
1500 inform the subsequent <code>fetch</code> command.</p></div>
1501 <div class="paragraph"><p>The client CAN issue <code>bundle-uri</code> before or after any other valid
1502 command. To be useful to clients it&#8217;s expected that it&#8217;ll be issued
1503 after an <code>ls-refs</code> and before <code>fetch</code>, but CAN be issued at any time
1504 in the dialog.</p></div>
1505 <div class="sect3">
1506 <h4 id="_discussion_of_bundle_uri">DISCUSSION of bundle-uri</h4>
1507 <div class="paragraph"><p>The intent of the feature is optimize for server resource consumption
1508 in the common case by changing the common case of fetching a very
1509 large PACK during <a href="git-clone.html">git-clone(1)</a> into a smaller incremental
1510 fetch.</p></div>
1511 <div class="paragraph"><p>It also allows servers to achieve better caching in combination with
1512 an <code>uploadpack.packObjectsHook</code> (see <a href="git-config.html">git-config(1)</a>).</p></div>
1513 <div class="paragraph"><p>By having new clones or fetches be a more predictable and common
1514 negotiation against the tips of recently produces *.bundle file(s).
1515 Servers might even pre-generate the results of such negotiations for
1516 the <code>uploadpack.packObjectsHook</code> as new pushes come in.</p></div>
1517 <div class="paragraph"><p>One way that servers could take advantage of these bundles is that the
1518 server would anticipate that fresh clones will download a known bundle,
1519 followed by catching up to the current state of the repository using ref
1520 tips found in that bundle (or bundles).</p></div>
1521 </div>
1522 <div class="sect3">
1523 <h4 id="_protocol_for_bundle_uri">PROTOCOL for bundle-uri</h4>
1524 <div class="paragraph"><p>A <code>bundle-uri</code> request takes no arguments, and as noted above does not
1525 currently advertise a capability value. Both may be added in the
1526 future.</p></div>
1527 <div class="paragraph"><p>When the client issues a <code>command=bundle-uri</code> request, the response is a
1528 list of key-value pairs provided as packet lines with value
1529 <code>&lt;key&gt;=&lt;value&gt;</code>. Each <code>&lt;key&gt;</code> should be interpreted as a config key from
1530 the <code>bundle.*</code> namespace to construct a list of bundles. These keys are
1531 grouped by a <code>bundle.&lt;id&gt;.</code> subsection, where each key corresponding to a
1532 given <code>&lt;id&gt;</code> contributes attributes to the bundle defined by that <code>&lt;id&gt;</code>.
1533 See <a href="git-config.html">git-config(1)</a> for the specific details of these keys and how
1534 the Git client will interpret their values.</p></div>
1535 <div class="paragraph"><p>Clients MUST parse the line according to the above format, lines that do
1536 not conform to the format SHOULD be discarded. The user MAY be warned in
1537 such a case.</p></div>
1538 </div>
1539 <div class="sect3">
1540 <h4 id="_bundle_uri_client_and_server_expectations">bundle-uri CLIENT AND SERVER EXPECTATIONS</h4>
1541 <div class="dlist"><dl>
1542 <dt class="hdlist1">
1543 URI CONTENTS
1544 </dt>
1545 <dd>
1546 <p>
1547 The content at the advertised URIs MUST be one of two types.
1548 </p>
1549 <div class="paragraph"><p>The advertised URI may contain a bundle file that <code>git bundle verify</code>
1550 would accept. I.e. they MUST contain one or more reference tips for
1551 use by the client, MUST indicate prerequisites (in any) with standard
1552 "-" prefixes, and MUST indicate their "object-format", if
1553 applicable.</p></div>
1554 <div class="paragraph"><p>The advertised URI may alternatively contain a plaintext file that <code>git
1555 config --list</code> would accept (with the <code>--file</code> option). The key-value
1556 pairs in this list are in the <code>bundle.*</code> namespace (see
1557 <a href="git-config.html">git-config(1)</a>).</p></div>
1558 </dd>
1559 <dt class="hdlist1">
1560 bundle-uri CLIENT ERROR RECOVERY
1561 </dt>
1562 <dd>
1563 <p>
1564 A client MUST above all gracefully degrade on errors, whether that
1565 error is because of bad missing/data in the bundle URI(s), because
1566 that client is too dumb to e.g. understand and fully parse out bundle
1567 headers and their prerequisite relationships, or something else.
1568 </p>
1569 <div class="paragraph"><p>Server operators should feel confident in turning on "bundle-uri" and
1570 not worry if e.g. their CDN goes down that clones or fetches will run
1571 into hard failures. Even if the server bundle(s) are
1572 incomplete, or bad in some way the client should still end up with a
1573 functioning repository, just as if it had chosen not to use this
1574 protocol extension.</p></div>
1575 <div class="paragraph"><p>All subsequent discussion on client and server interaction MUST keep
1576 this in mind.</p></div>
1577 </dd>
1578 <dt class="hdlist1">
1579 bundle-uri SERVER TO CLIENT
1580 </dt>
1581 <dd>
1582 <p>
1583 The ordering of the returned bundle uris is not significant. Clients
1584 MUST parse their headers to discover their contained OIDS and
1585 prerequisites. A client MUST consider the content of the bundle(s)
1586 themselves and their header as the ultimate source of truth.
1587 </p>
1588 <div class="paragraph"><p>A server MAY even return bundle(s) that don&#8217;t have any direct
1589 relationship to the repository being cloned (either through accident,
1590 or intentional "clever" configuration), and expect a client to sort
1591 out what data they&#8217;d like from the bundle(s), if any.</p></div>
1592 </dd>
1593 <dt class="hdlist1">
1594 bundle-uri CLIENT TO SERVER
1595 </dt>
1596 <dd>
1597 <p>
1598 The client SHOULD provide reference tips found in the bundle header(s)
1599 as <em>have</em> lines in any subsequent <code>fetch</code> request. A client MAY also
1600 ignore the bundle(s) entirely if doing so is deemed worse for some
1601 reason, e.g. if the bundles can&#8217;t be downloaded, it doesn&#8217;t like the
1602 tips it finds etc.
1603 </p>
1604 </dd>
1605 <dt class="hdlist1">
1606 WHEN ADVERTISED BUNDLE(S) REQUIRE NO FURTHER NEGOTIATION
1607 </dt>
1608 <dd>
1609 <p>
1610 If after issuing <code>bundle-uri</code> and <code>ls-refs</code>, and getting the header(s)
1611 of the bundle(s) the client finds that the ref tips it wants can be
1612 retrieved entirely from advertised bundle(s), the client MAY disconnect
1613 from the Git server. The results of such a <em>clone</em> or <em>fetch</em> should be
1614 indistinguishable from the state attained without using bundle-uri.
1615 </p>
1616 </dd>
1617 <dt class="hdlist1">
1618 EARLY CLIENT DISCONNECTIONS AND ERROR RECOVERY
1619 </dt>
1620 <dd>
1621 <p>
1622 A client MAY perform an early disconnect while still downloading the
1623 bundle(s) (having streamed and parsed their headers). In such a case
1624 the client MUST gracefully recover from any errors related to
1625 finishing the download and validation of the bundle(s).
1626 </p>
1627 <div class="paragraph"><p>I.e. a client might need to re-connect and issue a <em>fetch</em> command,
1628 and possibly fall back to not making use of <em>bundle-uri</em> at all.</p></div>
1629 <div class="paragraph"><p>This "MAY" behavior is specified as such (and not a "SHOULD") on the
1630 assumption that a server advertising bundle uris is more likely than
1631 not to be serving up a relatively large repository, and to be pointing
1632 to URIs that have a good chance of being in working order. A client
1633 MAY e.g. look at the payload size of the bundles as a heuristic to see
1634 if an early disconnect is worth it, should falling back on a full
1635 "fetch" dialog be necessary.</p></div>
1636 </dd>
1637 <dt class="hdlist1">
1638 WHEN ADVERTISED BUNDLE(S) REQUIRE FURTHER NEGOTIATION
1639 </dt>
1640 <dd>
1641 <p>
1642 A client SHOULD commence a negotiation of a PACK from the server via
1643 the "fetch" command using the OID tips found in advertised bundles,
1644 even if&#8217;s still in the process of downloading those bundle(s).
1645 </p>
1646 <div class="paragraph"><p>This allows for aggressive early disconnects from any interactive
1647 server dialog. The client blindly trusts that the advertised OID tips
1648 are relevant, and issues them as <em>have</em> lines, it then requests any
1649 tips it would like (usually from the "ls-refs" advertisement) via
1650 <em>want</em> lines. The server will then compute a (hopefully small) PACK
1651 with the expected difference between the tips from the bundle(s) and
1652 the data requested.</p></div>
1653 <div class="paragraph"><p>The only connection the client then needs to keep active is to the
1654 concurrently downloading static bundle(s), when those and the
1655 incremental PACK are retrieved they should be inflated and
1656 validated. Any errors at this point should be gracefully recovered
1657 from, see above.</p></div>
1658 </dd>
1659 </dl></div>
1660 </div>
1661 <div class="sect3">
1662 <h4 id="_bundle_uri_protocol_features">bundle-uri PROTOCOL FEATURES</h4>
1663 <div class="paragraph"><p>The client constructs a bundle list from the <code>&lt;key&gt;=&lt;value&gt;</code> pairs
1664 provided by the server. These pairs are part of the <code>bundle.*</code> namespace
1665 as documented in <a href="git-config.html">git-config(1)</a>. In this section, we discuss some
1666 of these keys and describe the actions the client will do in response to
1667 this information.</p></div>
1668 <div class="paragraph"><p>In particular, the <code>bundle.version</code> key specifies an integer value. The
1669 only accepted value at the moment is <code>1</code>, but if the client sees an
1670 unexpected value here then the client MUST ignore the bundle list.</p></div>
1671 <div class="paragraph"><p>As long as <code>bundle.version</code> is understood, all other unknown keys MAY be
1672 ignored by the client. The server will guarantee compatibility with older
1673 clients, though newer clients may be better able to use the extra keys to
1674 minimize downloads.</p></div>
1675 <div class="paragraph"><p>Any backwards-incompatible addition of pre-URI key-value will be
1676 guarded by a new <code>bundle.version</code> value or values in <em>bundle-uri</em>
1677 capability advertisement itself, and/or by new future <code>bundle-uri</code>
1678 request arguments.</p></div>
1679 <div class="paragraph"><p>Some example key-value pairs that are not currently implemented but could
1680 be implemented in the future include:</p></div>
1681 <div class="ulist"><ul>
1682 <li>
1683 <p>
1684 Add a "hash=&lt;val&gt;" or "size=&lt;bytes&gt;" advertise the expected hash or
1685    size of the bundle file.
1686 </p>
1687 </li>
1688 <li>
1689 <p>
1690 Advertise that one or more bundle files are the same (to e.g. have
1691    clients round-robin or otherwise choose one of N possible files).
1692 </p>
1693 </li>
1694 <li>
1695 <p>
1696 A "oid=&lt;OID&gt;" shortcut and "prerequisite=&lt;OID&gt;" shortcut. For
1697    expressing the common case of a bundle with one tip and no
1698    prerequisites, or one tip and one prerequisite.
1699 </p>
1700 <div class="paragraph"><p>This would allow for optimizing the common case of servers who&#8217;d like
1701 to provide one "big bundle" containing only their "main" branch,
1702 and/or incremental updates thereof.</p></div>
1703 <div class="paragraph"><p>A client receiving such a a response MAY assume that they can skip
1704 retrieving the header from a bundle at the indicated URI, and thus
1705 save themselves and the server(s) the request(s) needed to inspect the
1706 headers of that bundle or bundles.</p></div>
1707 </li>
1708 </ul></div>
1709 </div>
1710 </div>
1711 </div>
1712 </div>
1713 <div class="sect1">
1714 <h2 id="_git">GIT</h2>
1715 <div class="sectionbody">
1716 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1717 </div>
1718 </div>
1719 </div>
1720 <div id="footnotes"><hr /></div>
1721 <div id="footer">
1722 <div id="footer-text">
1723 Last updated
1724  2024-03-07 16:01:15 PST
1725 </div>
1726 </div>
1727 </body>
1728 </html>