gitprotocol-pack.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-pack(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-pack(5) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>gitprotocol-pack -
 743    How packs are transferred over-the-wire
 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>Git supports transferring data in packfiles over the ssh://, git://, http:// and
 761 file:// transports.  There exist two sets of protocols, one for pushing
 762 data from a client to a server and another for fetching data from a
 763 server to a client.  The three transports (ssh, git, file) use the same
 764 protocol to transfer data. http is documented in <a href="gitprotocol-http.html">gitprotocol-http(5)</a>.</p></div>
 765 <div class="paragraph"><p>The processes invoked in the canonical Git implementation are <em>upload-pack</em>
 766 on the server side and <em>fetch-pack</em> on the client side for fetching data;
 767 then <em>receive-pack</em> on the server and <em>send-pack</em> on the client for pushing
 768 data.  The protocol functions to have a server tell a client what is
 769 currently on the server, then for the two to negotiate the smallest amount
 770 of data to send in order to fully update one or the other.</p></div>
 771 </div>
 772 </div>
 773 <div class="sect1">
 774 <h2 id="_pkt_line_format">pkt-line Format</h2>
 775 <div class="sectionbody">
 776 <div class="paragraph"><p>The descriptions below build on the pkt-line format described in
 777 <a href="gitprotocol-common.html">gitprotocol-common(5)</a>. When the grammar indicates <code>PKT-LINE(...)</code>, unless
 778 otherwise noted the usual pkt-line LF rules apply: the sender SHOULD
 779 include a LF, but the receiver MUST NOT complain if it is not present.</p></div>
 780 <div class="paragraph"><p>An error packet is a special pkt-line that contains an error string.</p></div>
 781 <div class="listingblock">
 782 <div class="content">
 783 <pre><code>  error-line     =  PKT-LINE("ERR" SP explanation-text)</code></pre>
 784 </div></div>
 785 <div class="paragraph"><p>Throughout the protocol, where <code>PKT-LINE(...)</code> is expected, an error packet MAY
 786 be sent. Once this packet is sent by a client or a server, the data transfer
 787 process defined in this protocol is terminated.</p></div>
 788 </div>
 789 </div>
 790 <div class="sect1">
 791 <h2 id="_transports">Transports</h2>
 792 <div class="sectionbody">
 793 <div class="paragraph"><p>There are three transports over which the packfile protocol is
 794 initiated.  The Git transport is a simple, unauthenticated server that
 795 takes the command (almost always <em>upload-pack</em>, though Git
 796 servers can be configured to be globally writable, in which <em>receive-
 797 pack</em> initiation is also allowed) with which the client wishes to
 798 communicate and executes it and connects it to the requesting
 799 process.</p></div>
 800 <div class="paragraph"><p>In the SSH transport, the client just runs the <em>upload-pack</em>
 801 or <em>receive-pack</em> process on the server over the SSH protocol and then
 802 communicates with that invoked process over the SSH connection.</p></div>
 803 <div class="paragraph"><p>The file:// transport runs the <em>upload-pack</em> or <em>receive-pack</em>
 804 process locally and communicates with it over a pipe.</p></div>
 805 </div>
 806 </div>
 807 <div class="sect1">
 808 <h2 id="_extra_parameters">Extra Parameters</h2>
 809 <div class="sectionbody">
 810 <div class="paragraph"><p>The protocol provides a mechanism in which clients can send additional
 811 information in its first message to the server. These are called "Extra
 812 Parameters", and are supported by the Git, SSH, and HTTP protocols.</p></div>
 813 <div class="paragraph"><p>Each Extra Parameter takes the form of <code>&lt;key&gt;=&lt;value&gt;</code> or <code>&lt;key&gt;</code>.</p></div>
 814 <div class="paragraph"><p>Servers that receive any such Extra Parameters MUST ignore all
 815 unrecognized keys. Currently, the only Extra Parameter recognized is
 816 "version" with a value of <em>1</em> or <em>2</em>.  See <a href="gitprotocol-v2.html">gitprotocol-v2(5)</a> for more
 817 information on protocol version 2.</p></div>
 818 </div>
 819 </div>
 820 <div class="sect1">
 821 <h2 id="_git_transport">Git Transport</h2>
 822 <div class="sectionbody">
 823 <div class="paragraph"><p>The Git transport starts off by sending the command and repository
 824 on the wire using the pkt-line format, followed by a NUL byte and a
 825 hostname parameter, terminated by a NUL byte.</p></div>
 826 <div class="literalblock">
 827 <div class="content">
 828 <pre><code>0033git-upload-pack /project.git\0host=myserver.com\0</code></pre>
 829 </div></div>
 830 <div class="paragraph"><p>The transport may send Extra Parameters by adding an additional NUL
 831 byte, and then adding one or more NUL-terminated strings:</p></div>
 832 <div class="literalblock">
 833 <div class="content">
 834 <pre><code>003egit-upload-pack /project.git\0host=myserver.com\0\0version=1\0</code></pre>
 835 </div></div>
 836 <div class="openblock">
 837 <div class="content">
 838 <div class="literalblock">
 839 <div class="content">
 840 <pre><code>git-proto-request = request-command SP pathname NUL
 841                     [ host-parameter NUL ] [ NUL extra-parameters ]
 842 request-command   = "git-upload-pack" / "git-receive-pack" /
 843                     "git-upload-archive"   ; case sensitive
 844 pathname          = *( %x01-ff ) ; exclude NUL
 845 host-parameter    = "host=" hostname [ ":" port ]
 846 extra-parameters  = 1*extra-parameter
 847 extra-parameter   = 1*( %x01-ff ) NUL</code></pre>
 848 </div></div>
 849 </div></div>
 850 <div class="paragraph"><p>host-parameter is used for the
 851 git-daemon name based virtual hosting.  See --interpolated-path
 852 option to git daemon, with the %H/%CH format characters.</p></div>
 853 <div class="paragraph"><p>Basically what the Git client is doing to connect to an <em>upload-pack</em>
 854 process on the server side over the Git protocol is this:</p></div>
 855 <div class="literalblock">
 856 <div class="content">
 857 <pre><code>$ echo -e -n \
 858   "003agit-upload-pack /schacon/gitbook.git\0host=example.com\0" |
 859   nc -v example.com 9418</code></pre>
 860 </div></div>
 861 </div>
 862 </div>
 863 <div class="sect1">
 864 <h2 id="_ssh_transport">SSH Transport</h2>
 865 <div class="sectionbody">
 866 <div class="paragraph"><p>Initiating the upload-pack or receive-pack processes over SSH is
 867 executing the binary on the server via SSH remote execution.
 868 It is basically equivalent to running this:</p></div>
 869 <div class="literalblock">
 870 <div class="content">
 871 <pre><code>$ ssh git.example.com "git-upload-pack '/project.git'"</code></pre>
 872 </div></div>
 873 <div class="paragraph"><p>For a server to support Git pushing and pulling for a given user over
 874 SSH, that user needs to be able to execute one or both of those
 875 commands via the SSH shell that they are provided on login.  On some
 876 systems, that shell access is limited to only being able to run those
 877 two commands, or even just one of them.</p></div>
 878 <div class="paragraph"><p>In an ssh:// format URI, it&#8217;s absolute in the URI, so the <em>/</em> after
 879 the host name (or port number) is sent as an argument, which is then
 880 read by the remote git-upload-pack exactly as is, so it&#8217;s effectively
 881 an absolute path in the remote filesystem.</p></div>
 882 <div class="literalblock">
 883 <div class="content">
 884 <pre><code>   git clone ssh://user@example.com/project.git
 885                 |
 886                 v
 887 ssh user@example.com "git-upload-pack '/project.git'"</code></pre>
 888 </div></div>
 889 <div class="paragraph"><p>In a "user@host:path" format URI, it&#8217;s relative to the user&#8217;s home
 890 directory, because the Git client will run:</p></div>
 891 <div class="literalblock">
 892 <div class="content">
 893 <pre><code>   git clone user@example.com:project.git
 894                   |
 895                   v
 896 ssh user@example.com "git-upload-pack 'project.git'"</code></pre>
 897 </div></div>
 898 <div class="paragraph"><p>The exception is if a <em>~</em> is used, in which case
 899 we execute it without the leading <em>/</em>.</p></div>
 900 <div class="literalblock">
 901 <div class="content">
 902 <pre><code>   ssh://user@example.com/~alice/project.git,
 903                   |
 904                   v
 905 ssh user@example.com "git-upload-pack '~alice/project.git'"</code></pre>
 906 </div></div>
 907 <div class="paragraph"><p>Depending on the value of the <code>protocol.version</code> configuration variable,
 908 Git may attempt to send Extra Parameters as a colon-separated string in
 909 the GIT_PROTOCOL environment variable. This is done only if
 910 the <code>ssh.variant</code> configuration variable indicates that the ssh command
 911 supports passing environment variables as an argument.</p></div>
 912 <div class="paragraph"><p>A few things to remember here:</p></div>
 913 <div class="ulist"><ul>
 914 <li>
 915 <p>
 916 The "command name" is spelled with dash (e.g. git-upload-pack), but
 917   this can be overridden by the client;
 918 </p>
 919 </li>
 920 <li>
 921 <p>
 922 The repository path is always quoted with single quotes.
 923 </p>
 924 </li>
 925 </ul></div>
 926 </div>
 927 </div>
 928 <div class="sect1">
 929 <h2 id="_fetching_data_from_a_server">Fetching Data From a Server</h2>
 930 <div class="sectionbody">
 931 <div class="paragraph"><p>When one Git repository wants to get data that a second repository
 932 has, the first can <em>fetch</em> from the second.  This operation determines
 933 what data the server has that the client does not then streams that
 934 data down to the client in packfile format.</p></div>
 935 </div>
 936 </div>
 937 <div class="sect1">
 938 <h2 id="_reference_discovery">Reference Discovery</h2>
 939 <div class="sectionbody">
 940 <div class="paragraph"><p>When the client initially connects the server will immediately respond
 941 with a version number (if "version=1" is sent as an Extra Parameter),
 942 and a listing of each reference it has (all branches and tags) along
 943 with the object name that each reference currently points to.</p></div>
 944 <div class="literalblock">
 945 <div class="content">
 946 <pre><code>$ echo -e -n "0045git-upload-pack /schacon/gitbook.git\0host=example.com\0\0version=1\0" |
 947    nc -v example.com 9418
 948 000eversion 1
 949 00887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack
 950              side-band side-band-64k ofs-delta shallow no-progress include-tag
 951 00441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration
 952 003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master
 953 003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9
 954 003c525128480b96c89e6418b1e40909bf6c5b2d580f refs/tags/v1.0
 955 003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{}
 956 0000</code></pre>
 957 </div></div>
 958 <div class="paragraph"><p>The returned response is a pkt-line stream describing each ref and
 959 its current value.  The stream MUST be sorted by name according to
 960 the C locale ordering.</p></div>
 961 <div class="paragraph"><p>If HEAD is a valid ref, HEAD MUST appear as the first advertised
 962 ref.  If HEAD is not a valid ref, HEAD MUST NOT appear in the
 963 advertisement list at all, but other refs may still appear.</p></div>
 964 <div class="paragraph"><p>The stream MUST include capability declarations behind a NUL on the
 965 first ref. The peeled value of a ref (that is "ref^{}") MUST be
 966 immediately after the ref itself, if presented. A conforming server
 967 MUST peel the ref if it&#8217;s an annotated tag.</p></div>
 968 <div class="listingblock">
 969 <div class="content">
 970 <pre><code>  advertised-refs  =  *1("version 1")
 971                       (no-refs / list-of-refs)
 972                       *shallow
 973                       flush-pkt
 974
 975   no-refs          =  PKT-LINE(zero-id SP "capabilities^{}"
 976                       NUL capability-list)
 977
 978   list-of-refs     =  first-ref *other-ref
 979   first-ref        =  PKT-LINE(obj-id SP refname
 980                       NUL capability-list)
 981
 982   other-ref        =  PKT-LINE(other-tip / other-peeled)
 983   other-tip        =  obj-id SP refname
 984   other-peeled     =  obj-id SP refname "^{}"
 985
 986   shallow          =  PKT-LINE("shallow" SP obj-id)
 987
 988   capability-list  =  capability *(SP capability)
 989   capability       =  1*(LC_ALPHA / DIGIT / "-" / "_")
 990   LC_ALPHA         =  %x61-7A</code></pre>
 991 </div></div>
 992 <div class="paragraph"><p>Server and client MUST use lowercase for obj-id, both MUST treat obj-id
 993 as case-insensitive.</p></div>
 994 <div class="paragraph"><p>See protocol-capabilities.txt for a list of allowed server capabilities
 995 and descriptions.</p></div>
 996 </div>
 997 </div>
 998 <div class="sect1">
 999 <h2 id="_packfile_negotiation">Packfile Negotiation</h2>
1000 <div class="sectionbody">
1001 <div class="paragraph"><p>After reference and capabilities discovery, the client can decide to
1002 terminate the connection by sending a flush-pkt, telling the server it can
1003 now gracefully terminate, and disconnect, when it does not need any pack
1004 data. This can happen with the ls-remote command, and also can happen when
1005 the client already is up to date.</p></div>
1006 <div class="paragraph"><p>Otherwise, it enters the negotiation phase, where the client and
1007 server determine what the minimal packfile necessary for transport is,
1008 by telling the server what objects it wants, its shallow objects
1009 (if any), and the maximum commit depth it wants (if any).  The client
1010 will also send a list of the capabilities it wants to be in effect,
1011 out of what the server said it could do with the first <em>want</em> line.</p></div>
1012 <div class="listingblock">
1013 <div class="content">
1014 <pre><code>  upload-request    =  want-list
1015                        *shallow-line
1016                        *1depth-request
1017                        [filter-request]
1018                        flush-pkt
1019
1020   want-list         =  first-want
1021                        *additional-want
1022
1023   shallow-line      =  PKT-LINE("shallow" SP obj-id)
1024
1025   depth-request     =  PKT-LINE("deepen" SP depth) /
1026                        PKT-LINE("deepen-since" SP timestamp) /
1027                        PKT-LINE("deepen-not" SP ref)
1028
1029   first-want        =  PKT-LINE("want" SP obj-id SP capability-list)
1030   additional-want   =  PKT-LINE("want" SP obj-id)
1031
1032   depth             =  1*DIGIT
1033
1034   filter-request    =  PKT-LINE("filter" SP filter-spec)</code></pre>
1035 </div></div>
1036 <div class="paragraph"><p>Clients MUST send all the obj-ids it wants from the reference
1037 discovery phase as <em>want</em> lines. Clients MUST send at least one
1038 <em>want</em> command in the request body. Clients MUST NOT mention an
1039 obj-id in a <em>want</em> command which did not appear in the response
1040 obtained through ref discovery.</p></div>
1041 <div class="paragraph"><p>The client MUST write all obj-ids which it only has shallow copies
1042 of (meaning that it does not have the parents of a commit) as
1043 <em>shallow</em> lines so that the server is aware of the limitations of
1044 the client&#8217;s history.</p></div>
1045 <div class="paragraph"><p>The client now sends the maximum commit history depth it wants for
1046 this transaction, which is the number of commits it wants from the
1047 tip of the history, if any, as a <em>deepen</em> line.  A depth of 0 is the
1048 same as not making a depth request. The client does not want to receive
1049 any commits beyond this depth, nor does it want objects needed only to
1050 complete those commits. Commits whose parents are not received as a
1051 result are defined as shallow and marked as such in the server. This
1052 information is sent back to the client in the next step.</p></div>
1053 <div class="paragraph"><p>The client can optionally request that pack-objects omit various
1054 objects from the packfile using one of several filtering techniques.
1055 These are intended for use with partial clone and partial fetch
1056 operations. An object that does not meet a filter-spec value is
1057 omitted unless explicitly requested in a <em>want</em> line. See <code>rev-list</code>
1058 for possible filter-spec values.</p></div>
1059 <div class="paragraph"><p>Once all the <em>want&#8217;s and 'shallow&#8217;s (and optional 'deepen</em>) are
1060 transferred, clients MUST send a flush-pkt, to tell the server side
1061 that it is done sending the list.</p></div>
1062 <div class="paragraph"><p>Otherwise, if the client sent a positive depth request, the server
1063 will determine which commits will and will not be shallow and
1064 send this information to the client. If the client did not request
1065 a positive depth, this step is skipped.</p></div>
1066 <div class="listingblock">
1067 <div class="content">
1068 <pre><code>  shallow-update   =  *shallow-line
1069                       *unshallow-line
1070                       flush-pkt
1071
1072   shallow-line     =  PKT-LINE("shallow" SP obj-id)
1073
1074   unshallow-line   =  PKT-LINE("unshallow" SP obj-id)</code></pre>
1075 </div></div>
1076 <div class="paragraph"><p>If the client has requested a positive depth, the server will compute
1077 the set of commits which are no deeper than the desired depth. The set
1078 of commits starts at the client&#8217;s wants.</p></div>
1079 <div class="paragraph"><p>The server writes <em>shallow</em> lines for each
1080 commit whose parents will not be sent as a result. The server writes
1081 an <em>unshallow</em> line for each commit which the client has indicated is
1082 shallow, but is no longer shallow at the currently requested depth
1083 (that is, its parents will now be sent). The server MUST NOT mark
1084 as unshallow anything which the client has not indicated was shallow.</p></div>
1085 <div class="paragraph"><p>Now the client will send a list of the obj-ids it has using <em>have</em>
1086 lines, so the server can make a packfile that only contains the objects
1087 that the client needs. In multi_ack mode, the canonical implementation
1088 will send up to 32 of these at a time, then will send a flush-pkt. The
1089 canonical implementation will skip ahead and send the next 32 immediately,
1090 so that there is always a block of 32 "in-flight on the wire" at a time.</p></div>
1091 <div class="listingblock">
1092 <div class="content">
1093 <pre><code>  upload-haves      =  have-list
1094                        compute-end
1095
1096   have-list         =  *have-line
1097   have-line         =  PKT-LINE("have" SP obj-id)
1098   compute-end       =  flush-pkt / PKT-LINE("done")</code></pre>
1099 </div></div>
1100 <div class="paragraph"><p>If the server reads <em>have</em> lines, it then will respond by ACKing any
1101 of the obj-ids the client said it had that the server also has. The
1102 server will ACK obj-ids differently depending on which ack mode is
1103 chosen by the client.</p></div>
1104 <div class="paragraph"><p>In multi_ack mode:</p></div>
1105 <div class="ulist"><ul>
1106 <li>
1107 <p>
1108 the server will respond with <em>ACK obj-id continue</em> for any common
1109     commits.
1110 </p>
1111 </li>
1112 <li>
1113 <p>
1114 once the server has found an acceptable common base commit and is
1115     ready to make a packfile, it will blindly ACK all <em>have</em> obj-ids
1116     back to the client.
1117 </p>
1118 </li>
1119 <li>
1120 <p>
1121 the server will then send a <em>NAK</em> and then wait for another response
1122     from the client - either a <em>done</em> or another list of <em>have</em> lines.
1123 </p>
1124 </li>
1125 </ul></div>
1126 <div class="paragraph"><p>In multi_ack_detailed mode:</p></div>
1127 <div class="ulist"><ul>
1128 <li>
1129 <p>
1130 the server will differentiate the ACKs where it is signaling
1131     that it is ready to send data with <em>ACK obj-id ready</em> lines, and
1132     signals the identified common commits with <em>ACK obj-id common</em> lines.
1133 </p>
1134 </li>
1135 </ul></div>
1136 <div class="paragraph"><p>Without either multi_ack or multi_ack_detailed:</p></div>
1137 <div class="ulist"><ul>
1138 <li>
1139 <p>
1140 upload-pack sends "ACK obj-id" on the first common object it finds.
1141    After that it says nothing until the client gives it a "done".
1142 </p>
1143 </li>
1144 <li>
1145 <p>
1146 upload-pack sends "NAK" on a flush-pkt if no common object
1147    has been found yet.  If one has been found, and thus an ACK
1148    was already sent, it&#8217;s silent on the flush-pkt.
1149 </p>
1150 </li>
1151 </ul></div>
1152 <div class="paragraph"><p>After the client has gotten enough ACK responses that it can determine
1153 that the server has enough information to send an efficient packfile
1154 (in the canonical implementation, this is determined when it has received
1155 enough ACKs that it can color everything left in the --date-order queue
1156 as common with the server, or the --date-order queue is empty), or the
1157 client determines that it wants to give up (in the canonical implementation,
1158 this is determined when the client sends 256 <em>have</em> lines without getting
1159 any of them ACKed by the server - meaning there is nothing in common and
1160 the server should just send all of its objects), then the client will send
1161 a <em>done</em> command.  The <em>done</em> command signals to the server that the client
1162 is ready to receive its packfile data.</p></div>
1163 <div class="paragraph"><p>However, the 256 limit <strong>only</strong> turns on in the canonical client
1164 implementation if we have received at least one "ACK %s continue"
1165 during a prior round.  This helps to ensure that at least one common
1166 ancestor is found before we give up entirely.</p></div>
1167 <div class="paragraph"><p>Once the <em>done</em> line is read from the client, the server will either
1168 send a final <em>ACK obj-id</em> or it will send a <em>NAK</em>. <em>obj-id</em> is the object
1169 name of the last commit determined to be common. The server only sends
1170 ACK after <em>done</em> if there is at least one common base and multi_ack or
1171 multi_ack_detailed is enabled. The server always sends NAK after <em>done</em>
1172 if there is no common base found.</p></div>
1173 <div class="paragraph"><p>Instead of <em>ACK</em> or <em>NAK</em>, the server may send an error message (for
1174 example, if it does not recognize an object in a <em>want</em> line received
1175 from the client).</p></div>
1176 <div class="paragraph"><p>Then the server will start sending its packfile data.</p></div>
1177 <div class="listingblock">
1178 <div class="content">
1179 <pre><code>  server-response = *ack_multi ack / nak
1180   ack_multi       = PKT-LINE("ACK" SP obj-id ack_status)
1181   ack_status      = "continue" / "common" / "ready"
1182   ack             = PKT-LINE("ACK" SP obj-id)
1183   nak             = PKT-LINE("NAK")</code></pre>
1184 </div></div>
1185 <div class="paragraph"><p>A simple clone may look like this (with no <em>have</em> lines):</p></div>
1186 <div class="listingblock">
1187 <div class="content">
1188 <pre><code>   C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \
1189      side-band-64k ofs-delta\n
1190    C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n
1191    C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n
1192    C: 0032want 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n
1193    C: 0032want 74730d410fcb6603ace96f1dc55ea6196122532d\n
1194    C: 0000
1195    C: 0009done\n
1196
1197    S: 0008NAK\n
1198    S: [PACKFILE]</code></pre>
1199 </div></div>
1200 <div class="paragraph"><p>An incremental update (fetch) response might look like this:</p></div>
1201 <div class="listingblock">
1202 <div class="content">
1203 <pre><code>   C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \
1204      side-band-64k ofs-delta\n
1205    C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n
1206    C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n
1207    C: 0000
1208    C: 0032have 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n
1209    C: [30 more have lines]
1210    C: 0032have 74730d410fcb6603ace96f1dc55ea6196122532d\n
1211    C: 0000
1212
1213    S: 003aACK 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01 continue\n
1214    S: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d continue\n
1215    S: 0008NAK\n
1216
1217    C: 0009done\n
1218
1219    S: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\n
1220    S: [PACKFILE]</code></pre>
1221 </div></div>
1222 </div>
1223 </div>
1224 <div class="sect1">
1225 <h2 id="_packfile_data">Packfile Data</h2>
1226 <div class="sectionbody">
1227 <div class="paragraph"><p>Now that the client and server have finished negotiation about what
1228 the minimal amount of data that needs to be sent to the client is, the server
1229 will construct and send the required data in packfile format.</p></div>
1230 <div class="paragraph"><p>See <a href="gitformat-pack.html">gitformat-pack(5)</a> for what the packfile itself actually looks like.</p></div>
1231 <div class="paragraph"><p>If <em>side-band</em> or <em>side-band-64k</em> capabilities have been specified by
1232 the client, the server will send the packfile data multiplexed.</p></div>
1233 <div class="paragraph"><p>Each packet starting with the packet-line length of the amount of data
1234 that follows, followed by a single byte specifying the sideband the
1235 following data is coming in on.</p></div>
1236 <div class="paragraph"><p>In <em>side-band</em> mode, it will send up to 999 data bytes plus 1 control
1237 code, for a total of up to 1000 bytes in a pkt-line.  In <em>side-band-64k</em>
1238 mode it will send up to 65519 data bytes plus 1 control code, for a
1239 total of up to 65520 bytes in a pkt-line.</p></div>
1240 <div class="paragraph"><p>The sideband byte will be a <em>1</em>, <em>2</em> or a <em>3</em>. Sideband <em>1</em> will contain
1241 packfile data, sideband <em>2</em> will be used for progress information that the
1242 client will generally print to stderr and sideband <em>3</em> is used for error
1243 information.</p></div>
1244 <div class="paragraph"><p>If no <em>side-band</em> capability was specified, the server will stream the
1245 entire packfile without multiplexing.</p></div>
1246 </div>
1247 </div>
1248 <div class="sect1">
1249 <h2 id="_pushing_data_to_a_server">Pushing Data To a Server</h2>
1250 <div class="sectionbody">
1251 <div class="paragraph"><p>Pushing data to a server will invoke the <em>receive-pack</em> process on the
1252 server, which will allow the client to tell it which references it should
1253 update and then send all the data the server will need for those new
1254 references to be complete.  Once all the data is received and validated,
1255 the server will then update its references to what the client specified.</p></div>
1256 </div>
1257 </div>
1258 <div class="sect1">
1259 <h2 id="_authentication">Authentication</h2>
1260 <div class="sectionbody">
1261 <div class="paragraph"><p>The protocol itself contains no authentication mechanisms.  That is to be
1262 handled by the transport, such as SSH, before the <em>receive-pack</em> process is
1263 invoked.  If <em>receive-pack</em> is configured over the Git transport, those
1264 repositories will be writable by anyone who can access that port (9418) as
1265 that transport is unauthenticated.</p></div>
1266 </div>
1267 </div>
1268 <div class="sect1">
1269 <h2 id="_reference_discovery_2">Reference Discovery</h2>
1270 <div class="sectionbody">
1271 <div class="paragraph"><p>The reference discovery phase is done nearly the same way as it is in the
1272 fetching protocol. Each reference obj-id and name on the server is sent
1273 in packet-line format to the client, followed by a flush-pkt.  The only
1274 real difference is that the capability listing is different - the only
1275 possible values are <em>report-status</em>, <em>report-status-v2</em>, <em>delete-refs</em>,
1276 <em>ofs-delta</em>, <em>atomic</em> and <em>push-options</em>.</p></div>
1277 </div>
1278 </div>
1279 <div class="sect1">
1280 <h2 id="_reference_update_request_and_packfile_transfer">Reference Update Request and Packfile Transfer</h2>
1281 <div class="sectionbody">
1282 <div class="paragraph"><p>Once the client knows what references the server is at, it can send a
1283 list of reference update requests.  For each reference on the server
1284 that it wants to update, it sends a line listing the obj-id currently on
1285 the server, the obj-id the client would like to update it to and the name
1286 of the reference.</p></div>
1287 <div class="paragraph"><p>This list is followed by a flush-pkt.</p></div>
1288 <div class="listingblock">
1289 <div class="content">
1290 <pre><code>  update-requests   =  *shallow ( command-list | push-cert )
1291
1292   shallow           =  PKT-LINE("shallow" SP obj-id)
1293
1294   command-list      =  PKT-LINE(command NUL capability-list)
1295                        *PKT-LINE(command)
1296                        flush-pkt
1297
1298   command           =  create / delete / update
1299   create            =  zero-id SP new-id  SP name
1300   delete            =  old-id  SP zero-id SP name
1301   update            =  old-id  SP new-id  SP name
1302
1303   old-id            =  obj-id
1304   new-id            =  obj-id
1305
1306   push-cert         = PKT-LINE("push-cert" NUL capability-list LF)
1307                       PKT-LINE("certificate version 0.1" LF)
1308                       PKT-LINE("pusher" SP ident LF)
1309                       PKT-LINE("pushee" SP url LF)
1310                       PKT-LINE("nonce" SP nonce LF)
1311                       *PKT-LINE("push-option" SP push-option LF)
1312                       PKT-LINE(LF)
1313                       *PKT-LINE(command LF)
1314                       *PKT-LINE(gpg-signature-lines LF)
1315                       PKT-LINE("push-cert-end" LF)
1316
1317   push-option       =  1*( VCHAR | SP )</code></pre>
1318 </div></div>
1319 <div class="paragraph"><p>If the server has advertised the <em>push-options</em> capability and the client has
1320 specified <em>push-options</em> as part of the capability list above, the client then
1321 sends its push options followed by a flush-pkt.</p></div>
1322 <div class="listingblock">
1323 <div class="content">
1324 <pre><code>  push-options      =  *PKT-LINE(push-option) flush-pkt</code></pre>
1325 </div></div>
1326 <div class="paragraph"><p>For backwards compatibility with older Git servers, if the client sends a push
1327 cert and push options, it MUST send its push options both embedded within the
1328 push cert and after the push cert. (Note that the push options within the cert
1329 are prefixed, but the push options after the cert are not.) Both these lists
1330 MUST be the same, modulo the prefix.</p></div>
1331 <div class="paragraph"><p>After that the packfile that
1332 should contain all the objects that the server will need to complete the new
1333 references will be sent.</p></div>
1334 <div class="listingblock">
1335 <div class="content">
1336 <pre><code>  packfile          =  "PACK" 28*(OCTET)</code></pre>
1337 </div></div>
1338 <div class="paragraph"><p>If the receiving end does not support delete-refs, the sending end MUST
1339 NOT ask for delete command.</p></div>
1340 <div class="paragraph"><p>If the receiving end does not support push-cert, the sending end
1341 MUST NOT send a push-cert command.  When a push-cert command is
1342 sent, command-list MUST NOT be sent; the commands recorded in the
1343 push certificate is used instead.</p></div>
1344 <div class="paragraph"><p>The packfile MUST NOT be sent if the only command used is <em>delete</em>.</p></div>
1345 <div class="paragraph"><p>A packfile MUST be sent if either create or update command is used,
1346 even if the server already has all the necessary objects.  In this
1347 case the client MUST send an empty packfile.   The only time this
1348 is likely to happen is if the client is creating
1349 a new branch or a tag that points to an existing obj-id.</p></div>
1350 <div class="paragraph"><p>The server will receive the packfile, unpack it, then validate each
1351 reference that is being updated that it hasn&#8217;t changed while the request
1352 was being processed (the obj-id is still the same as the old-id), and
1353 it will run any update hooks to make sure that the update is acceptable.
1354 If all of that is fine, the server will then update the references.</p></div>
1355 </div>
1356 </div>
1357 <div class="sect1">
1358 <h2 id="_push_certificate">Push Certificate</h2>
1359 <div class="sectionbody">
1360 <div class="paragraph"><p>A push certificate begins with a set of header lines.  After the
1361 header and an empty line, the protocol commands follow, one per
1362 line. Note that the trailing LF in push-cert PKT-LINEs is <em>not</em>
1363 optional; it must be present.</p></div>
1364 <div class="paragraph"><p>Currently, the following header fields are defined:</p></div>
1365 <div class="dlist"><dl>
1366 <dt class="hdlist1">
1367 <code>pusher</code> ident
1368 </dt>
1369 <dd>
1370 <p>
1371         Identify the GPG key in "Human Readable Name &lt;<a href="mailto:email@address">email@address</a>&gt;"
1372         format.
1373 </p>
1374 </dd>
1375 <dt class="hdlist1">
1376 <code>pushee</code> url
1377 </dt>
1378 <dd>
1379 <p>
1380         The repository URL (anonymized, if the URL contains
1381         authentication material) the user who ran <code>git push</code>
1382         intended to push into.
1383 </p>
1384 </dd>
1385 <dt class="hdlist1">
1386 <code>nonce</code> nonce
1387 </dt>
1388 <dd>
1389 <p>
1390         The <em>nonce</em> string the receiving repository asked the
1391         pushing user to include in the certificate, to prevent
1392         replay attacks.
1393 </p>
1394 </dd>
1395 </dl></div>
1396 <div class="paragraph"><p>The GPG signature lines are a detached signature for the contents
1397 recorded in the push certificate before the signature block begins.
1398 The detached signature is used to certify that the commands were
1399 given by the pusher, who must be the signer.</p></div>
1400 </div>
1401 </div>
1402 <div class="sect1">
1403 <h2 id="_report_status">Report Status</h2>
1404 <div class="sectionbody">
1405 <div class="paragraph"><p>After receiving the pack data from the sender, the receiver sends a
1406 report if <em>report-status</em> or <em>report-status-v2</em> capability is in effect.
1407 It is a short listing of what happened in that update.  It will first
1408 list the status of the packfile unpacking as either <em>unpack ok</em> or
1409 <em>unpack [error]</em>.  Then it will list the status for each of the references
1410 that it tried to update.  Each line is either <em>ok [refname]</em> if the
1411 update was successful, or <em>ng [refname] [error]</em> if the update was not.</p></div>
1412 <div class="listingblock">
1413 <div class="content">
1414 <pre><code>  report-status     = unpack-status
1415                       1*(command-status)
1416                       flush-pkt
1417
1418   unpack-status     = PKT-LINE("unpack" SP unpack-result)
1419   unpack-result     = "ok" / error-msg
1420
1421   command-status    = command-ok / command-fail
1422   command-ok        = PKT-LINE("ok" SP refname)
1423   command-fail      = PKT-LINE("ng" SP refname SP error-msg)
1424
1425   error-msg         = 1*(OCTET) ; where not "ok"</code></pre>
1426 </div></div>
1427 <div class="paragraph"><p>The <em>report-status-v2</em> capability extends the protocol by adding new option
1428 lines in order to support reporting of reference rewritten by the
1429 <em>proc-receive</em> hook.  The <em>proc-receive</em> hook may handle a command for a
1430 pseudo-reference which may create or update one or more references, and each
1431 reference may have different name, different new-oid, and different old-oid.</p></div>
1432 <div class="listingblock">
1433 <div class="content">
1434 <pre><code>  report-status-v2  = unpack-status
1435                       1*(command-status-v2)
1436                       flush-pkt
1437
1438   unpack-status     = PKT-LINE("unpack" SP unpack-result)
1439   unpack-result     = "ok" / error-msg
1440
1441   command-status-v2 = command-ok-v2 / command-fail
1442   command-ok-v2     = command-ok
1443                       *option-line
1444
1445   command-ok        = PKT-LINE("ok" SP refname)
1446   command-fail      = PKT-LINE("ng" SP refname SP error-msg)
1447
1448   error-msg         = 1*(OCTET) ; where not "ok"
1449
1450   option-line       = *1(option-refname)
1451                       *1(option-old-oid)
1452                       *1(option-new-oid)
1453                       *1(option-forced-update)
1454
1455   option-refname    = PKT-LINE("option" SP "refname" SP refname)
1456   option-old-oid    = PKT-LINE("option" SP "old-oid" SP obj-id)
1457   option-new-oid    = PKT-LINE("option" SP "new-oid" SP obj-id)
1458   option-force      = PKT-LINE("option" SP "forced-update")</code></pre>
1459 </div></div>
1460 <div class="paragraph"><p>Updates can be unsuccessful for a number of reasons.  The reference can have
1461 changed since the reference discovery phase was originally sent, meaning
1462 someone pushed in the meantime.  The reference being pushed could be a
1463 non-fast-forward reference and the update hooks or configuration could be
1464 set to not allow that, etc.  Also, some references can be updated while others
1465 can be rejected.</p></div>
1466 <div class="paragraph"><p>An example client/server communication might look like this:</p></div>
1467 <div class="listingblock">
1468 <div class="content">
1469 <pre><code>   S: 006274730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\0report-status delete-refs ofs-delta\n
1470    S: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug\n
1471    S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master\n
1472    S: 003d74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\n
1473    S: 0000
1474
1475    C: 00677d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\n
1476    C: 006874730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\n
1477    C: 0000
1478    C: [PACKDATA]
1479
1480    S: 000eunpack ok\n
1481    S: 0018ok refs/heads/debug\n
1482    S: 002ang refs/heads/master non-fast-forward\n</code></pre>
1483 </div></div>
1484 </div>
1485 </div>
1486 <div class="sect1">
1487 <h2 id="_git">GIT</h2>
1488 <div class="sectionbody">
1489 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1490 </div>
1491 </div>
1492 </div>
1493 <div id="footnotes"><hr /></div>
1494 <div id="footer">
1495 <div id="footer-text">
1496 Last updated
1497  2023-10-23 14:43:46 PDT
1498 </div>
1499 </div>
1500 </body>
1501 </html>