Google Git
Sign in
chromium / external / gitster / git-htmldocs / 85f1fdef295d40098c723afbbbc650101868d697 / . / technical / pack-protocol.html
blob: ab3e7330830ab7dfe9ed83291234d5e48f784340 [file] [log] [blame]
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
2 "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
3<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
4<head>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]5<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]6<meta name="generator" content="AsciiDoc 8.6.9" />
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]7<title>Packfile transfer protocols</title>
8<style type="text/css">
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]9/* Shared CSS for AsciiDoc xhtml11 and html5 backends */
10
11/* Default font. */
12body {
13 font-family: Georgia,serif;
14}
15
16/* Title font. */
17h1, h2, h3, h4, h5, h6,
18div.title, caption.title,
19thead, p.table.header,
20#toctitle,
21#author, #revnumber, #revdate, #revremark,
22#footer {
23 font-family: Arial,Helvetica,sans-serif;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]24}
25
26body {
27 margin: 1em 5% 1em 5%;
28}
29
30a {
31 color: blue;
32 text-decoration: underline;
33}
34a:visited {
35 color: fuchsia;
36}
37
38em {
39 font-style: italic;
40 color: navy;
41}
42
43strong {
44 font-weight: bold;
45 color: #083194;
46}
47
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]48h1, h2, h3, h4, h5, h6 {
49 color: #527bbd;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]50 margin-top: 1.2em;
51 margin-bottom: 0.5em;
52 line-height: 1.3;
53}
54
55h1, h2, h3 {
56 border-bottom: 2px solid silver;
57}
58h2 {
59 padding-top: 0.5em;
60}
61h3 {
62 float: left;
63}
64h3 + * {
65 clear: left;
66}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]67h5 {
68 font-size: 1.0em;
69}
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]70
71div.sectionbody {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]72 margin-left: 0;
73}
74
75hr {
76 border: 1px solid silver;
77}
78
79p {
80 margin-top: 0.5em;
81 margin-bottom: 0.5em;
82}
83
84ul, ol, li > p {
85 margin-top: 0;
86}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]87ul > li { color: #aaa; }
88ul > li > * { color: black; }
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]89
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]90.monospaced, code, pre {
91 font-family: "Courier New", Courier, monospace;
92 font-size: inherit;
93 color: navy;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]94 padding: 0;
95 margin: 0;
96}
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]97pre {
98 white-space: pre-wrap;
99}
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]100
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]101#author {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]102 color: #527bbd;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]103 font-weight: bold;
104 font-size: 1.1em;
105}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]106#email {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]107}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]108#revnumber, #revdate, #revremark {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]109}
110
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]111#footer {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]112 font-size: small;
113 border-top: 2px solid silver;
114 padding-top: 0.5em;
115 margin-top: 4.0em;
116}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]117#footer-text {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]118 float: left;
119 padding-bottom: 0.5em;
120}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]121#footer-badges {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]122 float: right;
123 padding-bottom: 0.5em;
124}
125
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]126#preamble {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]127 margin-top: 1.5em;
128 margin-bottom: 1.5em;
129}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]130div.imageblock, div.exampleblock, div.verseblock,
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]131div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
132div.admonitionblock {
133 margin-top: 1.0em;
134 margin-bottom: 1.5em;
135}
136div.admonitionblock {
137 margin-top: 2.0em;
138 margin-bottom: 2.0em;
139 margin-right: 10%;
140 color: #606060;
141}
142
143div.content { /* Block element content. */
144 padding: 0;
145}
146
147/* Block element titles. */
148div.title, caption.title {
149 color: #527bbd;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]150 font-weight: bold;
151 text-align: left;
152 margin-top: 1.0em;
153 margin-bottom: 0.5em;
154}
155div.title + * {
156 margin-top: 0;
157}
158
159td div.title:first-child {
160 margin-top: 0.0em;
161}
162div.content div.title:first-child {
163 margin-top: 0.0em;
164}
165div.content + div.title {
166 margin-top: 0.0em;
167}
168
169div.sidebarblock > div.content {
170 background: #ffffee;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]171 border: 1px solid #dddddd;
172 border-left: 4px solid #f0f0f0;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]173 padding: 0.5em;
174}
175
176div.listingblock > div.content {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]177 border: 1px solid #dddddd;
178 border-left: 5px solid #f0f0f0;
179 background: #f8f8f8;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]180 padding: 0.5em;
181}
182
183div.quoteblock, div.verseblock {
184 padding-left: 1.0em;
185 margin-left: 1.0em;
186 margin-right: 10%;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]187 border-left: 5px solid #f0f0f0;
188 color: #888;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]189}
190
191div.quoteblock > div.attribution {
192 padding-top: 0.5em;
193 text-align: right;
194}
195
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]196div.verseblock > pre.content {
197 font-family: inherit;
198 font-size: inherit;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]199}
200div.verseblock > div.attribution {
201 padding-top: 0.75em;
202 text-align: left;
203}
204/* DEPRECATED: Pre version 8.2.7 verse style literal block. */
205div.verseblock + div.attribution {
206 text-align: left;
207}
208
209div.admonitionblock .icon {
210 vertical-align: top;
211 font-size: 1.1em;
212 font-weight: bold;
213 text-decoration: underline;
214 color: #527bbd;
215 padding-right: 0.5em;
216}
217div.admonitionblock td.content {
218 padding-left: 0.5em;
219 border-left: 3px solid #dddddd;
220}
221
222div.exampleblock > div.content {
223 border-left: 3px solid #dddddd;
224 padding-left: 0.5em;
225}
226
227div.imageblock div.content { padding-left: 0; }
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]228span.image img { border-style: none; vertical-align: text-bottom; }
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]229a.image:visited { color: white; }
230
231dl {
232 margin-top: 0.8em;
233 margin-bottom: 0.8em;
234}
235dt {
236 margin-top: 0.5em;
237 margin-bottom: 0;
238 font-style: normal;
239 color: navy;
240}
241dd > *:first-child {
242 margin-top: 0.1em;
243}
244
245ul, ol {
246 list-style-position: outside;
247}
248ol.arabic {
249 list-style-type: decimal;
250}
251ol.loweralpha {
252 list-style-type: lower-alpha;
253}
254ol.upperalpha {
255 list-style-type: upper-alpha;
256}
257ol.lowerroman {
258 list-style-type: lower-roman;
259}
260ol.upperroman {
261 list-style-type: upper-roman;
262}
263
264div.compact ul, div.compact ol,
265div.compact p, div.compact p,
266div.compact div, div.compact div {
267 margin-top: 0.1em;
268 margin-bottom: 0.1em;
269}
270
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]271tfoot {
272 font-weight: bold;
273}
274td > div.verse {
275 white-space: pre;
276}
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]277
278div.hdlist {
279 margin-top: 0.8em;
280 margin-bottom: 0.8em;
281}
282div.hdlist tr {
283 padding-bottom: 15px;
284}
285dt.hdlist1.strong, td.hdlist1.strong {
286 font-weight: bold;
287}
288td.hdlist1 {
289 vertical-align: top;
290 font-style: normal;
291 padding-right: 0.8em;
292 color: navy;
293}
294td.hdlist2 {
295 vertical-align: top;
296}
297div.hdlist.compact tr {
298 margin: 0;
299 padding-bottom: 0;
300}
301
302.comment {
303 background: yellow;
304}
305
306.footnote, .footnoteref {
307 font-size: 0.8em;
308}
309
310span.footnote, span.footnoteref {
311 vertical-align: super;
312}
313
314#footnotes {
315 margin: 20px 0 20px 0;
316 padding: 7px 0 0 0;
317}
318
319#footnotes div.footnote {
320 margin: 0 0 5px 0;
321}
322
323#footnotes hr {
324 border: none;
325 border-top: 1px solid silver;
326 height: 1px;
327 text-align: left;
328 margin-left: 0;
329 width: 20%;
330 min-width: 100px;
331}
332
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]333div.colist td {
334 padding-right: 0.5em;
335 padding-bottom: 0.3em;
336 vertical-align: top;
337}
338div.colist td img {
339 margin-top: 0.3em;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]340}
341
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]342@media print {
343 #footer-badges { display: none; }
344}
345
346#toc {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]347 margin-bottom: 2.5em;
348}
349
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]350#toctitle {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]351 color: #527bbd;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]352 font-size: 1.1em;
353 font-weight: bold;
354 margin-top: 1.0em;
355 margin-bottom: 0.1em;
356}
357
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]358div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]359 margin-top: 0;
360 margin-bottom: 0;
361}
362div.toclevel2 {
363 margin-left: 2em;
364 font-size: 0.9em;
365}
366div.toclevel3 {
367 margin-left: 4em;
368 font-size: 0.9em;
369}
370div.toclevel4 {
371 margin-left: 6em;
372 font-size: 0.9em;
373}
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]374
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]375span.aqua { color: aqua; }
376span.black { color: black; }
377span.blue { color: blue; }
378span.fuchsia { color: fuchsia; }
379span.gray { color: gray; }
380span.green { color: green; }
381span.lime { color: lime; }
382span.maroon { color: maroon; }
383span.navy { color: navy; }
384span.olive { color: olive; }
385span.purple { color: purple; }
386span.red { color: red; }
387span.silver { color: silver; }
388span.teal { color: teal; }
389span.white { color: white; }
390span.yellow { color: yellow; }
391
392span.aqua-background { background: aqua; }
393span.black-background { background: black; }
394span.blue-background { background: blue; }
395span.fuchsia-background { background: fuchsia; }
396span.gray-background { background: gray; }
397span.green-background { background: green; }
398span.lime-background { background: lime; }
399span.maroon-background { background: maroon; }
400span.navy-background { background: navy; }
401span.olive-background { background: olive; }
402span.purple-background { background: purple; }
403span.red-background { background: red; }
404span.silver-background { background: silver; }
405span.teal-background { background: teal; }
406span.white-background { background: white; }
407span.yellow-background { background: yellow; }
408
409span.big { font-size: 2em; }
410span.small { font-size: 0.6em; }
411
412span.underline { text-decoration: underline; }
413span.overline { text-decoration: overline; }
414span.line-through { text-decoration: line-through; }
415
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]416div.unbreakable { page-break-inside: avoid; }
417
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]418
419/*
420 * xhtml11 specific
421 *
422 * */
423
424div.tableblock {
425 margin-top: 1.0em;
426 margin-bottom: 1.5em;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]427}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]428div.tableblock > table {
429 border: 3px solid #527bbd;
430}
431thead, p.table.header {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]432 font-weight: bold;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]433 color: #527bbd;
434}
435p.table {
436 margin-top: 0;
437}
438/* Because the table frame attribute is overriden by CSS in most browsers. */
439div.tableblock > table[frame="void"] {
440 border-style: none;
441}
442div.tableblock > table[frame="hsides"] {
443 border-left-style: none;
444 border-right-style: none;
445}
446div.tableblock > table[frame="vsides"] {
447 border-top-style: none;
448 border-bottom-style: none;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]449}
450
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]451
452/*
453 * html5 specific
454 *
455 * */
456
457table.tableblock {
458 margin-top: 1.0em;
459 margin-bottom: 1.5em;
460}
461thead, p.tableblock.header {
462 font-weight: bold;
463 color: #527bbd;
464}
465p.tableblock {
466 margin-top: 0;
467}
468table.tableblock {
469 border-width: 3px;
470 border-spacing: 0px;
471 border-style: solid;
472 border-color: #527bbd;
473 border-collapse: collapse;
474}
475th.tableblock, td.tableblock {
476 border-width: 1px;
477 padding: 4px;
478 border-style: solid;
479 border-color: #527bbd;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]480}
481
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]482table.tableblock.frame-topbot {
483 border-left-style: hidden;
484 border-right-style: hidden;
485}
486table.tableblock.frame-sides {
487 border-top-style: hidden;
488 border-bottom-style: hidden;
489}
490table.tableblock.frame-none {
491 border-style: hidden;
492}
493
494th.tableblock.halign-left, td.tableblock.halign-left {
495 text-align: left;
496}
497th.tableblock.halign-center, td.tableblock.halign-center {
498 text-align: center;
499}
500th.tableblock.halign-right, td.tableblock.halign-right {
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]501 text-align: right;
502}
503
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]504th.tableblock.valign-top, td.tableblock.valign-top {
505 vertical-align: top;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]506}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]507th.tableblock.valign-middle, td.tableblock.valign-middle {
508 vertical-align: middle;
509}
510th.tableblock.valign-bottom, td.tableblock.valign-bottom {
511 vertical-align: bottom;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]512}
513
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]514
515/*
516 * manpage specific
517 *
518 * */
519
520body.manpage h1 {
521 padding-top: 0.5em;
522 padding-bottom: 0.5em;
523 border-top: 2px solid silver;
524 border-bottom: 2px solid silver;
525}
526body.manpage h2 {
527 border-style: none;
528}
529body.manpage div.sectionbody {
530 margin-left: 3em;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]531}
532
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]533@media print {
534 body.manpage div#toc { display: none; }
535}
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]536
537
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]538</style>
539<script type="text/javascript">
540/*<![CDATA[*/
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]541var asciidoc = { // Namespace.
542
543/////////////////////////////////////////////////////////////////////
544// Table Of Contents generator
545/////////////////////////////////////////////////////////////////////
546
547/* Author: Mihai Bazon, September 2002
548 * http://students.infoiasi.ro/~mishoo
549 *
550 * Table Of Content generator
551 * Version: 0.4
552 *
553 * Feel free to use this script under the terms of the GNU General Public
554 * License, as long as you do not remove or alter this notice.
555 */
556
557 /* modified by Troy D. Hanson, September 2006. License: GPL */
558 /* modified by Stuart Rackham, 2006, 2009. License: GPL */
559
560// toclevels = 1..4.
561toc: function (toclevels) {
562
563 function getText(el) {
564 var text = "";
565 for (var i = el.firstChild; i != null; i = i.nextSibling) {
566 if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
567 text += i.data;
568 else if (i.firstChild != null)
569 text += getText(i);
570 }
571 return text;
572 }
573
574 function TocEntry(el, text, toclevel) {
575 this.element = el;
576 this.text = text;
577 this.toclevel = toclevel;
578 }
579
580 function tocEntries(el, toclevels) {
581 var result = new Array;
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]582 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]583 // Function that scans the DOM tree for header elements (the DOM2
584 // nodeIterator API would be a better technique but not supported by all
585 // browsers).
586 var iterate = function (el) {
587 for (var i = el.firstChild; i != null; i = i.nextSibling) {
588 if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
589 var mo = re.exec(i.tagName);
590 if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
591 result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
592 }
593 iterate(i);
594 }
595 }
596 }
597 iterate(el);
598 return result;
599 }
600
601 var toc = document.getElementById("toc");
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]602 if (!toc) {
603 return;
604 }
605
606 // Delete existing TOC entries in case we're reloading the TOC.
607 var tocEntriesToRemove = [];
608 var i;
609 for (i = 0; i < toc.childNodes.length; i++) {
610 var entry = toc.childNodes[i];
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]611 if (entry.nodeName.toLowerCase() == 'div'
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]612 && entry.getAttribute("class")
613 && entry.getAttribute("class").match(/^toclevel/))
614 tocEntriesToRemove.push(entry);
615 }
616 for (i = 0; i < tocEntriesToRemove.length; i++) {
617 toc.removeChild(tocEntriesToRemove[i]);
618 }
619
620 // Rebuild TOC entries.
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]621 var entries = tocEntries(document.getElementById("content"), toclevels);
622 for (var i = 0; i < entries.length; ++i) {
623 var entry = entries[i];
624 if (entry.element.id == "")
625 entry.element.id = "_toc_" + i;
626 var a = document.createElement("a");
627 a.href = "#" + entry.element.id;
628 a.appendChild(document.createTextNode(entry.text));
629 var div = document.createElement("div");
630 div.appendChild(a);
631 div.className = "toclevel" + entry.toclevel;
632 toc.appendChild(div);
633 }
634 if (entries.length == 0)
635 toc.parentNode.removeChild(toc);
636},
637
638
639/////////////////////////////////////////////////////////////////////
640// Footnotes generator
641/////////////////////////////////////////////////////////////////////
642
643/* Based on footnote generation code from:
644 * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
645 */
646
647footnotes: function () {
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]648 // Delete existing footnote entries in case we're reloading the footnodes.
649 var i;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]650 var noteholder = document.getElementById("footnotes");
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]651 if (!noteholder) {
652 return;
653 }
654 var entriesToRemove = [];
655 for (i = 0; i < noteholder.childNodes.length; i++) {
656 var entry = noteholder.childNodes[i];
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]657 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]658 entriesToRemove.push(entry);
659 }
660 for (i = 0; i < entriesToRemove.length; i++) {
661 noteholder.removeChild(entriesToRemove[i]);
662 }
663
664 // Rebuild footnote entries.
665 var cont = document.getElementById("content");
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]666 var spans = cont.getElementsByTagName("span");
667 var refs = {};
668 var n = 0;
669 for (i=0; i<spans.length; i++) {
670 if (spans[i].className == "footnote") {
671 n++;
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]672 var note = spans[i].getAttribute("data-note");
673 if (!note) {
674 // Use [\s\S] in place of . so multi-line matches work.
675 // Because JavaScript has no s (dotall) regex flag.
676 note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
677 spans[i].innerHTML =
678 "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
679 "' title='View footnote' class='footnote'>" + n + "</a>]";
680 spans[i].setAttribute("data-note", note);
681 }
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]682 noteholder.innerHTML +=
683 "<div class='footnote' id='_footnote_" + n + "'>" +
684 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
685 n + "</a>. " + note + "</div>";
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]686 var id =spans[i].getAttribute("id");
687 if (id != null) refs["#"+id] = n;
688 }
689 }
690 if (n == 0)
691 noteholder.parentNode.removeChild(noteholder);
692 else {
693 // Process footnoterefs.
694 for (i=0; i<spans.length; i++) {
695 if (spans[i].className == "footnoteref") {
696 var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
697 href = href.match(/#.*/)[0]; // Because IE return full URL.
698 n = refs[href];
699 spans[i].innerHTML =
700 "[<a href='#_footnote_" + n +
701 "' title='View footnote' class='footnote'>" + n + "</a>]";
702 }
703 }
704 }
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]705},
706
707install: function(toclevels) {
708 var timerId;
709
710 function reinstall() {
711 asciidoc.footnotes();
712 if (toclevels) {
713 asciidoc.toc(toclevels);
714 }
715 }
716
717 function reinstallAndRemoveTimer() {
718 clearInterval(timerId);
719 reinstall();
720 }
721
722 timerId = setInterval(reinstall, 500);
723 if (document.addEventListener)
724 document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
725 else
726 window.onload = reinstallAndRemoveTimer;
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]727}
728
729}
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]730asciidoc.install();
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]731/*]]>*/
732</script>
733</head>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]734<body class="article">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]735<div id="header">
736<h1>Packfile transfer protocols</h1>
737</div>
738<div id="content">
739<div id="preamble">
740<div class="sectionbody">
741<div class="paragraph"><p>Git supports transferring data in packfiles over the ssh://, git:// and
742file:// transports. There exist two sets of protocols, one for pushing
743data from a client to a server and another for fetching data from a
744server to a client. All three transports (ssh, git, file) use the same
745protocol to transfer data.</p></div>
746<div class="paragraph"><p>The processes invoked in the canonical Git implementation are <em>upload-pack</em>
747on the server side and <em>fetch-pack</em> on the client side for fetching data;
748then <em>receive-pack</em> on the server and <em>send-pack</em> on the client for pushing
749data. The protocol functions to have a server tell a client what is
750currently on the server, then for the two to negotiate the smallest amount
751of data to send in order to fully update one or the other.</p></div>
752</div>
753</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]754<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]755<h2 id="_transports">Transports</h2>
756<div class="sectionbody">
757<div class="paragraph"><p>There are three transports over which the packfile protocol is
758initiated. The Git transport is a simple, unauthenticated server that
759takes the command (almost always <em>upload-pack</em>, though Git
760servers can be configured to be globally writable, in which <em>receive-
761pack</em> initiation is also allowed) with which the client wishes to
762communicate and executes it and connects it to the requesting
763process.</p></div>
764<div class="paragraph"><p>In the SSH transport, the client just runs the <em>upload-pack</em>
765or <em>receive-pack</em> process on the server over the SSH protocol and then
766communicates with that invoked process over the SSH connection.</p></div>
767<div class="paragraph"><p>The file:// transport runs the <em>upload-pack</em> or <em>receive-pack</em>
768process locally and communicates with it over a pipe.</p></div>
769</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]770</div>
771<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]772<h2 id="_git_transport">Git Transport</h2>
773<div class="sectionbody">
774<div class="paragraph"><p>The Git transport starts off by sending the command and repository
775on the wire using the pkt-line format, followed by a NUL byte and a
776hostname parameter, terminated by a NUL byte.</p></div>
777<div class="literalblock">
778<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]779<pre><code>0032git-upload-pack /project.git\0host=myserver.com\0</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]780</div></div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]781<div class="openblock">
782<div class="content">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]783<div class="literalblock">
784<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]785<pre><code>git-proto-request = request-command SP pathname NUL [ host-parameter NUL ]
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]786request-command = "git-upload-pack" / "git-receive-pack" /
787 "git-upload-archive" ; case sensitive
788pathname = *( %x01-ff ) ; exclude NUL
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]789host-parameter = "host=" hostname [ ":" port ]</code></pre>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]790</div></div>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]791</div></div>
792<div class="paragraph"><p>Only host-parameter is allowed in the git-proto-request. Clients
793MUST NOT attempt to send additional parameters. It is used for the
794git-daemon name based virtual hosting. See --interpolated-path
795option to git daemon, with the %H/%CH format characters.</p></div>
796<div class="paragraph"><p>Basically what the Git client is doing to connect to an <em>upload-pack</em>
797process on the server side over the Git protocol is this:</p></div>
798<div class="literalblock">
799<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]800<pre><code>$ echo -e -n \
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]801 "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" |
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]802 nc -v example.com 9418</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]803</div></div>
804<div class="paragraph"><p>If the server refuses the request for some reasons, it could abort
805gracefully with an error message.</p></div>
806<div class="listingblock">
807<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]808<pre><code> error-line = PKT-LINE("ERR" SP explanation-text)</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]809</div></div>
810</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]811</div>
812<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]813<h2 id="_ssh_transport">SSH Transport</h2>
814<div class="sectionbody">
815<div class="paragraph"><p>Initiating the upload-pack or receive-pack processes over SSH is
816executing the binary on the server via SSH remote execution.
817It is basically equivalent to running this:</p></div>
818<div class="literalblock">
819<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]820<pre><code>$ ssh git.example.com "git-upload-pack '/project.git'"</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]821</div></div>
822<div class="paragraph"><p>For a server to support Git pushing and pulling for a given user over
823SSH, that user needs to be able to execute one or both of those
824commands via the SSH shell that they are provided on login. On some
825systems, that shell access is limited to only being able to run those
826two commands, or even just one of them.</p></div>
827<div class="paragraph"><p>In an ssh:// format URI, it&#8217;s absolute in the URI, so the <em>/</em> after
828the host name (or port number) is sent as an argument, which is then
829read by the remote git-upload-pack exactly as is, so it&#8217;s effectively
830an absolute path in the remote filesystem.</p></div>
831<div class="literalblock">
832<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]833<pre><code> git clone ssh://user@example.com/project.git
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]834 |
835 v
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]836ssh user@example.com "git-upload-pack '/project.git'"</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]837</div></div>
838<div class="paragraph"><p>In a "user@host:path" format URI, its relative to the user&#8217;s home
839directory, because the Git client will run:</p></div>
840<div class="literalblock">
841<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]842<pre><code> git clone user@example.com:project.git
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]843 |
844 v
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]845ssh user@example.com "git-upload-pack 'project.git'"</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]846</div></div>
847<div class="paragraph"><p>The exception is if a <em>~</em> is used, in which case
848we execute it without the leading <em>/</em>.</p></div>
849<div class="literalblock">
850<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]851<pre><code> ssh://user@example.com/~alice/project.git,
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]852 |
853 v
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]854ssh user@example.com "git-upload-pack '~alice/project.git'"</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]855</div></div>
856<div class="paragraph"><p>A few things to remember here:</p></div>
857<div class="ulist"><ul>
858<li>
859<p>
860The "command name" is spelled with dash (e.g. git-upload-pack), but
861 this can be overridden by the client;
862</p>
863</li>
864<li>
865<p>
866The repository path is always quoted with single quotes.
867</p>
868</li>
869</ul></div>
870</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]871</div>
872<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]873<h2 id="_fetching_data_from_a_server">Fetching Data From a Server</h2>
874<div class="sectionbody">
875<div class="paragraph"><p>When one Git repository wants to get data that a second repository
876has, the first can <em>fetch</em> from the second. This operation determines
877what data the server has that the client does not then streams that
878data down to the client in packfile format.</p></div>
879</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]880</div>
881<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]882<h2 id="_reference_discovery">Reference Discovery</h2>
883<div class="sectionbody">
884<div class="paragraph"><p>When the client initially connects the server will immediately respond
885with a listing of each reference it has (all branches and tags) along
886with the object name that each reference currently points to.</p></div>
887<div class="literalblock">
888<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]889<pre><code>$ echo -e -n "0039git-upload-pack /schacon/gitbook.git\0host=example.com\0" |
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]890 nc -v example.com 9418
89100887217a7c7e582c46cec22a130adf4b9d7d950fba0 HEAD\0multi_ack thin-pack
892 side-band side-band-64k ofs-delta shallow no-progress include-tag
89300441d3fcd5ced445d1abc402225c0b8a1299641f497 refs/heads/integration
894003f7217a7c7e582c46cec22a130adf4b9d7d950fba0 refs/heads/master
895003cb88d2441cac0977faf98efc80305012112238d9d refs/tags/v0.9
896003c525128480b96c89e6418b1e40909bf6c5b2d580f refs/tags/v1.0
897003fe92df48743b7bc7d26bcaabfddde0a1e20cae47c refs/tags/v1.0^{}
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]8980000</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]899</div></div>
900<div class="paragraph"><p>Server SHOULD terminate each non-flush line using LF ("\n") terminator;
901client MUST NOT complain if there is no terminator.</p></div>
902<div class="paragraph"><p>The returned response is a pkt-line stream describing each ref and
903its current value. The stream MUST be sorted by name according to
904the C locale ordering.</p></div>
905<div class="paragraph"><p>If HEAD is a valid ref, HEAD MUST appear as the first advertised
906ref. If HEAD is not a valid ref, HEAD MUST NOT appear in the
907advertisement list at all, but other refs may still appear.</p></div>
908<div class="paragraph"><p>The stream MUST include capability declarations behind a NUL on the
909first ref. The peeled value of a ref (that is "ref^{}") MUST be
910immediately after the ref itself, if presented. A conforming server
911MUST peel the ref if it&#8217;s an annotated tag.</p></div>
912<div class="listingblock">
913<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]914<pre><code> advertised-refs = (no-refs / list-of-refs)
Junio C Hamano61525f92014-01-17 22:46:49[diff] [blame]915 *shallow
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]916 flush-pkt
917
918 no-refs = PKT-LINE(zero-id SP "capabilities^{}"
919 NUL capability-list LF)
920
921 list-of-refs = first-ref *other-ref
922 first-ref = PKT-LINE(obj-id SP refname
923 NUL capability-list LF)
924
925 other-ref = PKT-LINE(other-tip / other-peeled)
926 other-tip = obj-id SP refname LF
927 other-peeled = obj-id SP refname "^{}" LF
928
Junio C Hamano61525f92014-01-17 22:46:49[diff] [blame]929 shallow = PKT-LINE("shallow" SP obj-id)
930
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]931 capability-list = capability *(SP capability)
932 capability = 1*(LC_ALPHA / DIGIT / "-" / "_")
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]933 LC_ALPHA = %x61-7A</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]934</div></div>
935<div class="paragraph"><p>Server and client MUST use lowercase for obj-id, both MUST treat obj-id
936as case-insensitive.</p></div>
937<div class="paragraph"><p>See protocol-capabilities.txt for a list of allowed server capabilities
938and descriptions.</p></div>
939</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]940</div>
941<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]942<h2 id="_packfile_negotiation">Packfile Negotiation</h2>
943<div class="sectionbody">
944<div class="paragraph"><p>After reference and capabilities discovery, the client can decide to
945terminate the connection by sending a flush-pkt, telling the server it can
946now gracefully terminate, and disconnect, when it does not need any pack
947data. This can happen with the ls-remote command, and also can happen when
948the client already is up-to-date.</p></div>
949<div class="paragraph"><p>Otherwise, it enters the negotiation phase, where the client and
950server determine what the minimal packfile necessary for transport is,
951by telling the server what objects it wants, its shallow objects
952(if any), and the maximum commit depth it wants (if any). The client
953will also send a list of the capabilities it wants to be in effect,
954out of what the server said it could do with the first <em>want</em> line.</p></div>
955<div class="listingblock">
956<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]957<pre><code> upload-request = want-list
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]958 *shallow-line
959 *1depth-request
960 flush-pkt
961
962 want-list = first-want
963 *additional-want
964
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]965 shallow-line = PKT-LINE("shallow" SP obj-id)
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]966
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]967 depth-request = PKT-LINE("deepen" SP depth)
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]968
969 first-want = PKT-LINE("want" SP obj-id SP capability-list LF)
970 additional-want = PKT-LINE("want" SP obj-id LF)
971
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]972 depth = 1*DIGIT</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]973</div></div>
974<div class="paragraph"><p>Clients MUST send all the obj-ids it wants from the reference
975discovery phase as <em>want</em> lines. Clients MUST send at least one
976<em>want</em> command in the request body. Clients MUST NOT mention an
977obj-id in a <em>want</em> command which did not appear in the response
978obtained through ref discovery.</p></div>
979<div class="paragraph"><p>The client MUST write all obj-ids which it only has shallow copies
980of (meaning that it does not have the parents of a commit) as
981<em>shallow</em> lines so that the server is aware of the limitations of
Junio C Hamanoc7102962013-05-29 23:57:17[diff] [blame]982the client&#8217;s history.</p></div>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]983<div class="paragraph"><p>The client now sends the maximum commit history depth it wants for
984this transaction, which is the number of commits it wants from the
985tip of the history, if any, as a <em>deepen</em> line. A depth of 0 is the
986same as not making a depth request. The client does not want to receive
Junio C Hamanod75148a2014-04-08 19:48:38[diff] [blame]987any commits beyond this depth, nor does it want objects needed only to
988complete those commits. Commits whose parents are not received as a
989result are defined as shallow and marked as such in the server. This
990information is sent back to the client in the next step.</p></div>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]991<div class="paragraph"><p>Once all the <em>want&#8217;s and 'shallow&#8217;s (and optional 'deepen</em>) are
992transferred, clients MUST send a flush-pkt, to tell the server side
993that it is done sending the list.</p></div>
994<div class="paragraph"><p>Otherwise, if the client sent a positive depth request, the server
995will determine which commits will and will not be shallow and
996send this information to the client. If the client did not request
997a positive depth, this step is skipped.</p></div>
998<div class="listingblock">
999<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1000<pre><code> shallow-update = *shallow-line
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1001 *unshallow-line
1002 flush-pkt
1003
1004 shallow-line = PKT-LINE("shallow" SP obj-id)
1005
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1006 unshallow-line = PKT-LINE("unshallow" SP obj-id)</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1007</div></div>
1008<div class="paragraph"><p>If the client has requested a positive depth, the server will compute
1009the set of commits which are no deeper than the desired depth. The set
1010of commits start at the client&#8217;s wants.</p></div>
1011<div class="paragraph"><p>The server writes <em>shallow</em> lines for each
1012commit whose parents will not be sent as a result. The server writes
1013an <em>unshallow</em> line for each commit which the client has indicated is
1014shallow, but is no longer shallow at the currently requested depth
1015(that is, its parents will now be sent). The server MUST NOT mark
1016as unshallow anything which the client has not indicated was shallow.</p></div>
1017<div class="paragraph"><p>Now the client will send a list of the obj-ids it has using <em>have</em>
1018lines, so the server can make a packfile that only contains the objects
1019that the client needs. In multi_ack mode, the canonical implementation
1020will send up to 32 of these at a time, then will send a flush-pkt. The
1021canonical implementation will skip ahead and send the next 32 immediately,
1022so that there is always a block of 32 "in-flight on the wire" at a time.</p></div>
1023<div class="listingblock">
1024<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1025<pre><code> upload-haves = have-list
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1026 compute-end
1027
1028 have-list = *have-line
1029 have-line = PKT-LINE("have" SP obj-id LF)
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1030 compute-end = flush-pkt / PKT-LINE("done")</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1031</div></div>
1032<div class="paragraph"><p>If the server reads <em>have</em> lines, it then will respond by ACKing any
1033of the obj-ids the client said it had that the server also has. The
1034server will ACK obj-ids differently depending on which ack mode is
1035chosen by the client.</p></div>
1036<div class="paragraph"><p>In multi_ack mode:</p></div>
1037<div class="ulist"><ul>
1038<li>
1039<p>
1040the server will respond with <em>ACK obj-id continue</em> for any common
1041 commits.
1042</p>
1043</li>
1044<li>
1045<p>
1046once the server has found an acceptable common base commit and is
1047 ready to make a packfile, it will blindly ACK all <em>have</em> obj-ids
1048 back to the client.
1049</p>
1050</li>
1051<li>
1052<p>
1053the server will then send a <em>NACK</em> and then wait for another response
1054 from the client - either a <em>done</em> or another list of <em>have</em> lines.
1055</p>
1056</li>
1057</ul></div>
1058<div class="paragraph"><p>In multi_ack_detailed mode:</p></div>
1059<div class="ulist"><ul>
1060<li>
1061<p>
1062the server will differentiate the ACKs where it is signaling
1063 that it is ready to send data with <em>ACK obj-id ready</em> lines, and
1064 signals the identified common commits with <em>ACK obj-id common</em> lines.
1065</p>
1066</li>
1067</ul></div>
1068<div class="paragraph"><p>Without either multi_ack or multi_ack_detailed:</p></div>
1069<div class="ulist"><ul>
1070<li>
1071<p>
1072upload-pack sends "ACK obj-id" on the first common object it finds.
1073 After that it says nothing until the client gives it a "done".
1074</p>
1075</li>
1076<li>
1077<p>
1078upload-pack sends "NAK" on a flush-pkt if no common object
1079 has been found yet. If one has been found, and thus an ACK
1080 was already sent, it&#8217;s silent on the flush-pkt.
1081</p>
1082</li>
1083</ul></div>
1084<div class="paragraph"><p>After the client has gotten enough ACK responses that it can determine
1085that the server has enough information to send an efficient packfile
1086(in the canonical implementation, this is determined when it has received
1087enough ACKs that it can color everything left in the --date-order queue
1088as common with the server, or the --date-order queue is empty), or the
1089client determines that it wants to give up (in the canonical implementation,
1090this is determined when the client sends 256 <em>have</em> lines without getting
1091any of them ACKed by the server - meaning there is nothing in common and
1092the server should just send all of its objects), then the client will send
1093a <em>done</em> command. The <em>done</em> command signals to the server that the client
1094is ready to receive its packfile data.</p></div>
1095<div class="paragraph"><p>However, the 256 limit <strong>only</strong> turns on in the canonical client
1096implementation if we have received at least one "ACK %s continue"
1097during a prior round. This helps to ensure that at least one common
1098ancestor is found before we give up entirely.</p></div>
1099<div class="paragraph"><p>Once the <em>done</em> line is read from the client, the server will either
Junio C Hamano5b3533d2014-02-27 23:07:15[diff] [blame]1100send a final <em>ACK obj-id</em> or it will send a <em>NAK</em>. <em>obj-id</em> is the object
1101name of the last commit determined to be common. The server only sends
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1102ACK after <em>done</em> if there is at least one common base and multi_ack or
1103multi_ack_detailed is enabled. The server always sends NAK after <em>done</em>
1104if there is no common base found.</p></div>
1105<div class="paragraph"><p>Then the server will start sending its packfile data.</p></div>
1106<div class="listingblock">
1107<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1108<pre><code> server-response = *ack_multi ack / nak
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1109 ack_multi = PKT-LINE("ACK" SP obj-id ack_status LF)
1110 ack_status = "continue" / "common" / "ready"
1111 ack = PKT-LINE("ACK SP obj-id LF)
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1112 nak = PKT-LINE("NAK" LF)</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1113</div></div>
1114<div class="paragraph"><p>A simple clone may look like this (with no <em>have</em> lines):</p></div>
1115<div class="listingblock">
1116<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1117<pre><code> C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1118 side-band-64k ofs-delta\n
1119 C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n
1120 C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n
1121 C: 0032want 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n
1122 C: 0032want 74730d410fcb6603ace96f1dc55ea6196122532d\n
1123 C: 0000
1124 C: 0009done\n
1125
1126 S: 0008NAK\n
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1127 S: [PACKFILE]</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1128</div></div>
1129<div class="paragraph"><p>An incremental update (fetch) response might look like this:</p></div>
1130<div class="listingblock">
1131<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1132<pre><code> C: 0054want 74730d410fcb6603ace96f1dc55ea6196122532d multi_ack \
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1133 side-band-64k ofs-delta\n
1134 C: 0032want 7d1665144a3a975c05f1f43902ddaf084e784dbe\n
1135 C: 0032want 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a\n
1136 C: 0000
1137 C: 0032have 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01\n
1138 C: [30 more have lines]
1139 C: 0032have 74730d410fcb6603ace96f1dc55ea6196122532d\n
1140 C: 0000
1141
1142 S: 003aACK 7e47fe2bd8d01d481f44d7af0531bd93d3b21c01 continue\n
1143 S: 003aACK 74730d410fcb6603ace96f1dc55ea6196122532d continue\n
1144 S: 0008NAK\n
1145
1146 C: 0009done\n
1147
1148 S: 0031ACK 74730d410fcb6603ace96f1dc55ea6196122532d\n
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1149 S: [PACKFILE]</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1150</div></div>
1151</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1152</div>
1153<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1154<h2 id="_packfile_data">Packfile Data</h2>
1155<div class="sectionbody">
1156<div class="paragraph"><p>Now that the client and server have finished negotiation about what
1157the minimal amount of data that needs to be sent to the client is, the server
1158will construct and send the required data in packfile format.</p></div>
1159<div class="paragraph"><p>See pack-format.txt for what the packfile itself actually looks like.</p></div>
1160<div class="paragraph"><p>If <em>side-band</em> or <em>side-band-64k</em> capabilities have been specified by
1161the client, the server will send the packfile data multiplexed.</p></div>
1162<div class="paragraph"><p>Each packet starting with the packet-line length of the amount of data
1163that follows, followed by a single byte specifying the sideband the
1164following data is coming in on.</p></div>
1165<div class="paragraph"><p>In <em>side-band</em> mode, it will send up to 999 data bytes plus 1 control
1166code, for a total of up to 1000 bytes in a pkt-line. In <em>side-band-64k</em>
1167mode it will send up to 65519 data bytes plus 1 control code, for a
1168total of up to 65520 bytes in a pkt-line.</p></div>
1169<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
1170packfile data, sideband <em>2</em> will be used for progress information that the
1171client will generally print to stderr and sideband <em>3</em> is used for error
1172information.</p></div>
1173<div class="paragraph"><p>If no <em>side-band</em> capability was specified, the server will stream the
1174entire packfile without multiplexing.</p></div>
1175</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1176</div>
1177<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1178<h2 id="_pushing_data_to_a_server">Pushing Data To a Server</h2>
1179<div class="sectionbody">
1180<div class="paragraph"><p>Pushing data to a server will invoke the <em>receive-pack</em> process on the
1181server, which will allow the client to tell it which references it should
1182update and then send all the data the server will need for those new
1183references to be complete. Once all the data is received and validated,
1184the server will then update its references to what the client specified.</p></div>
1185</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1186</div>
1187<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1188<h2 id="_authentication">Authentication</h2>
1189<div class="sectionbody">
1190<div class="paragraph"><p>The protocol itself contains no authentication mechanisms. That is to be
1191handled by the transport, such as SSH, before the <em>receive-pack</em> process is
1192invoked. If <em>receive-pack</em> is configured over the Git transport, those
1193repositories will be writable by anyone who can access that port (9418) as
1194that transport is unauthenticated.</p></div>
1195</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1196</div>
1197<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1198<h2 id="_reference_discovery_2">Reference Discovery</h2>
1199<div class="sectionbody">
1200<div class="paragraph"><p>The reference discovery phase is done nearly the same way as it is in the
1201fetching protocol. Each reference obj-id and name on the server is sent
1202in packet-line format to the client, followed by a flush-pkt. The only
1203real difference is that the capability listing is different - the only
1204possible values are <em>report-status</em>, <em>delete-refs</em> and <em>ofs-delta</em>.</p></div>
1205</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1206</div>
1207<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1208<h2 id="_reference_update_request_and_packfile_transfer">Reference Update Request and Packfile Transfer</h2>
1209<div class="sectionbody">
1210<div class="paragraph"><p>Once the client knows what references the server is at, it can send a
1211list of reference update requests. For each reference on the server
1212that it wants to update, it sends a line listing the obj-id currently on
1213the server, the obj-id the client would like to update it to and the name
1214of the reference.</p></div>
1215<div class="paragraph"><p>This list is followed by a flush-pkt and then the packfile that should
1216contain all the objects that the server will need to complete the new
1217references.</p></div>
1218<div class="listingblock">
1219<div class="content">
Junio C Hamano1dbca522015-05-22 20:48:55[diff] [blame]1220<pre><code> update-request = *shallow ( command-list | push-cert ) [packfile]
Junio C Hamano61525f92014-01-17 22:46:49[diff] [blame]1221
Junio C Hamano53fe0312014-09-09 21:16:17[diff] [blame]1222 shallow = PKT-LINE("shallow" SP obj-id LF)
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1223
1224 command-list = PKT-LINE(command NUL capability-list LF)
1225 *PKT-LINE(command LF)
1226 flush-pkt
1227
1228 command = create / delete / update
1229 create = zero-id SP new-id SP name
1230 delete = old-id SP zero-id SP name
1231 update = old-id SP new-id SP name
1232
1233 old-id = obj-id
1234 new-id = obj-id
1235
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1236 push-cert = PKT-LINE("push-cert" NUL capability-list LF)
1237 PKT-LINE("certificate version 0.1" LF)
1238 PKT-LINE("pusher" SP ident LF)
1239 PKT-LINE("pushee" SP url LF)
1240 PKT-LINE("nonce" SP nonce LF)
1241 PKT-LINE(LF)
1242 *PKT-LINE(command LF)
1243 *PKT-LINE(gpg-signature-lines LF)
1244 PKT-LINE("push-cert-end" LF)
1245
Junio C Hamano1dbca522015-05-22 20:48:55[diff] [blame]1246 packfile = "PACK" 28*(OCTET)</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1247</div></div>
1248<div class="paragraph"><p>If the receiving end does not support delete-refs, the sending end MUST
1249NOT ask for delete command.</p></div>
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1250<div class="paragraph"><p>If the receiving end does not support push-cert, the sending end
1251MUST NOT send a push-cert command. When a push-cert command is
1252sent, command-list MUST NOT be sent; the commands recorded in the
1253push certificate is used instead.</p></div>
Junio C Hamano1dbca522015-05-22 20:48:55[diff] [blame]1254<div class="paragraph"><p>The packfile MUST NOT be sent if the only command used is <em>delete</em>.</p></div>
1255<div class="paragraph"><p>A packfile MUST be sent if either create or update command is used,
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1256even if the server already has all the necessary objects. In this
Junio C Hamano1dbca522015-05-22 20:48:55[diff] [blame]1257case the client MUST send an empty packfile. The only time this
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1258is likely to happen is if the client is creating
1259a new branch or a tag that points to an existing obj-id.</p></div>
1260<div class="paragraph"><p>The server will receive the packfile, unpack it, then validate each
1261reference that is being updated that it hasn&#8217;t changed while the request
1262was being processed (the obj-id is still the same as the old-id), and
1263it will run any update hooks to make sure that the update is acceptable.
1264If all of that is fine, the server will then update the references.</p></div>
1265</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1266</div>
1267<div class="sect1">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1268<h2 id="_push_certificate">Push Certificate</h2>
1269<div class="sectionbody">
1270<div class="paragraph"><p>A push certificate begins with a set of header lines. After the
1271header and an empty line, the protocol commands follow, one per
1272line.</p></div>
1273<div class="paragraph"><p>Currently, the following header fields are defined:</p></div>
1274<div class="dlist"><dl>
1275<dt class="hdlist1">
1276<code>pusher</code> ident
1277</dt>
1278<dd>
1279<p>
1280 Identify the GPG key in "Human Readable Name &lt;<a href="mailto:email@address">email@address</a>&gt;"
1281 format.
1282</p>
1283</dd>
1284<dt class="hdlist1">
1285<code>pushee</code> url
1286</dt>
1287<dd>
1288<p>
1289 The repository URL (anonymized, if the URL contains
1290 authentication material) the user who ran <code>git push</code>
1291 intended to push into.
1292</p>
1293</dd>
1294<dt class="hdlist1">
1295<code>nonce</code> nonce
1296</dt>
1297<dd>
1298<p>
1299 The <em>nonce</em> string the receiving repository asked the
1300 pushing user to include in the certificate, to prevent
1301 replay attacks.
1302</p>
1303</dd>
1304</dl></div>
1305<div class="paragraph"><p>The GPG signature lines are a detached signature for the contents
1306recorded in the push certificate before the signature block begins.
1307The detached signature is used to certify that the commands were
1308given by the pusher, who must be the signer.</p></div>
1309</div>
1310</div>
1311<div class="sect1">
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1312<h2 id="_report_status">Report Status</h2>
1313<div class="sectionbody">
1314<div class="paragraph"><p>After receiving the pack data from the sender, the receiver sends a
1315report if <em>report-status</em> capability is in effect.
1316It is a short listing of what happened in that update. It will first
1317list the status of the packfile unpacking as either <em>unpack ok</em> or
1318<em>unpack [error]</em>. Then it will list the status for each of the references
1319that it tried to update. Each line is either <em>ok [refname]</em> if the
1320update was successful, or <em>ng [refname] [error]</em> if the update was not.</p></div>
1321<div class="listingblock">
1322<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1323<pre><code> report-status = unpack-status
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1324 1*(command-status)
1325 flush-pkt
1326
1327 unpack-status = PKT-LINE("unpack" SP unpack-result LF)
1328 unpack-result = "ok" / error-msg
1329
1330 command-status = command-ok / command-fail
1331 command-ok = PKT-LINE("ok" SP refname LF)
1332 command-fail = PKT-LINE("ng" SP refname SP error-msg LF)
1333
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1334 error-msg = 1*(OCTECT) ; where not "ok"</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1335</div></div>
1336<div class="paragraph"><p>Updates can be unsuccessful for a number of reasons. The reference can have
1337changed since the reference discovery phase was originally sent, meaning
1338someone pushed in the meantime. The reference being pushed could be a
1339non-fast-forward reference and the update hooks or configuration could be
1340set to not allow that, etc. Also, some references can be updated while others
1341can be rejected.</p></div>
1342<div class="paragraph"><p>An example client/server communication might look like this:</p></div>
1343<div class="listingblock">
1344<div class="content">
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1345<pre><code> S: 007c74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/local\0report-status delete-refs ofs-delta\n
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1346 S: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe refs/heads/debug\n
1347 S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/master\n
1348 S: 003f74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/team\n
1349 S: 0000
1350
1351 C: 003e7d1665144a3a975c05f1f43902ddaf084e784dbe 74730d410fcb6603ace96f1dc55ea6196122532d refs/heads/debug\n
1352 C: 003e74730d410fcb6603ace96f1dc55ea6196122532d 5a3f6be755bbb7deae50065988cbfa1ffa9ab68a refs/heads/master\n
1353 C: 0000
1354 C: [PACKDATA]
1355
1356 S: 000eunpack ok\n
1357 S: 0018ok refs/heads/debug\n
Junio C Hamano9236fea2014-10-14 22:28:09[diff] [blame]1358 S: 002ang refs/heads/master non-fast-forward\n</code></pre>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1359</div></div>
1360</div>
1361</div>
Junio C Hamano9d971152012-12-19 00:43:11[diff] [blame]1362</div>
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1363<div id="footnotes"><hr /></div>
1364<div id="footer">
1365<div id="footer-text">
Junio C Hamano1dbca522015-05-22 20:48:55[diff] [blame]1366Last updated 2015-05-22 13:47:07 PDT
Junio C Hamanof2b74942012-11-20 21:06:26[diff] [blame]1367</div>
1368</div>
1369</body>
1370</html>