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