Google Git
Sign in
chromium / external / gitster / git-htmldocs / 85f1fdef295d40098c723afbbbc650101868d697 / . / technical / http-protocol.html
blob: ecf1356057db9e4010824a345a9af4609111f7cb [file] [log] [blame]
Junio C Hamanoc5bd79e2014-01-27 21:31: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>
5<meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]6<meta name="generator" content="AsciiDoc 8.6.9" />
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]7<title>HTTP transfer protocols</title>
8<style type="text/css">
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;
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
48h1, h2, h3, h4, h5, h6 {
49 color: #527bbd;
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}
67h5 {
68 font-size: 1.0em;
69}
70
71div.sectionbody {
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}
87ul > li { color: #aaa; }
88ul > li > * { color: black; }
89
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]90.monospaced, code, pre {
91 font-family: "Courier New", Courier, monospace;
92 font-size: inherit;
93 color: navy;
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]94 padding: 0;
95 margin: 0;
96}
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]97pre {
98 white-space: pre-wrap;
99}
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]100
101#author {
102 color: #527bbd;
103 font-weight: bold;
104 font-size: 1.1em;
105}
106#email {
107}
108#revnumber, #revdate, #revremark {
109}
110
111#footer {
112 font-size: small;
113 border-top: 2px solid silver;
114 padding-top: 0.5em;
115 margin-top: 4.0em;
116}
117#footer-text {
118 float: left;
119 padding-bottom: 0.5em;
120}
121#footer-badges {
122 float: right;
123 padding-bottom: 0.5em;
124}
125
126#preamble {
127 margin-top: 1.5em;
128 margin-bottom: 1.5em;
129}
130div.imageblock, div.exampleblock, div.verseblock,
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;
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;
171 border: 1px solid #dddddd;
172 border-left: 4px solid #f0f0f0;
173 padding: 0.5em;
174}
175
176div.listingblock > div.content {
177 border: 1px solid #dddddd;
178 border-left: 5px solid #f0f0f0;
179 background: #f8f8f8;
180 padding: 0.5em;
181}
182
183div.quoteblock, div.verseblock {
184 padding-left: 1.0em;
185 margin-left: 1.0em;
186 margin-right: 10%;
187 border-left: 5px solid #f0f0f0;
188 color: #888;
189}
190
191div.quoteblock > div.attribution {
192 padding-top: 0.5em;
193 text-align: right;
194}
195
196div.verseblock > pre.content {
197 font-family: inherit;
198 font-size: inherit;
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 Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]228span.image img { border-style: none; vertical-align: text-bottom; }
Junio C Hamanoc5bd79e2014-01-27 21:31: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
271tfoot {
272 font-weight: bold;
273}
274td > div.verse {
275 white-space: pre;
276}
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
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;
340}
341
342@media print {
343 #footer-badges { display: none; }
344}
345
346#toc {
347 margin-bottom: 2.5em;
348}
349
350#toctitle {
351 color: #527bbd;
352 font-size: 1.1em;
353 font-weight: bold;
354 margin-top: 1.0em;
355 margin-bottom: 0.1em;
356}
357
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]358div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
Junio C Hamanoc5bd79e2014-01-27 21:31: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}
374
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 Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]416div.unbreakable { page-break-inside: avoid; }
417
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]418
419/*
420 * xhtml11 specific
421 *
422 * */
423
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]424div.tableblock {
425 margin-top: 1.0em;
426 margin-bottom: 1.5em;
427}
428div.tableblock > table {
429 border: 3px solid #527bbd;
430}
431thead, p.table.header {
432 font-weight: bold;
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;
449}
450
451
452/*
453 * html5 specific
454 *
455 * */
456
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]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;
480}
481
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 {
501 text-align: right;
502}
503
504th.tableblock.valign-top, td.tableblock.valign-top {
505 vertical-align: top;
506}
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;
512}
513
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;
531}
532
533@media print {
534 body.manpage div#toc { display: none; }
535}
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]536
537
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]538</style>
539<script type="text/javascript">
540/*<![CDATA[*/
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 Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]582 var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
Junio C Hamanoc5bd79e2014-01-27 21:31: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");
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 Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]611 if (entry.nodeName.toLowerCase() == 'div'
Junio C Hamanoc5bd79e2014-01-27 21:31:26[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.
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 () {
648 // Delete existing footnote entries in case we're reloading the footnodes.
649 var i;
650 var noteholder = document.getElementById("footnotes");
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 Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]657 if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
Junio C Hamanoc5bd79e2014-01-27 21:31:26[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");
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++;
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 }
682 noteholder.innerHTML +=
683 "<div class='footnote' id='_footnote_" + n + "'>" +
684 "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
685 n + "</a>. " + note + "</div>";
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 }
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;
727}
728
729}
730asciidoc.install();
731/*]]>*/
732</script>
733</head>
734<body class="article">
735<div id="header">
736<h1>HTTP transfer protocols</h1>
737</div>
738<div id="content">
739<div id="preamble">
740<div class="sectionbody">
741<div class="paragraph"><p>Git supports two HTTP based transfer protocols. A "dumb" protocol
742which requires only a standard HTTP server on the server end of the
743connection, and a "smart" protocol which requires a Git aware CGI
744(or server module). This document describes both protocols.</p></div>
745<div class="paragraph"><p>As a design feature smart clients can automatically upgrade "dumb"
746protocol URLs to smart URLs. This permits all users to have the
747same published URL, and the peers automatically select the most
748efficient transport available to them.</p></div>
749</div>
750</div>
751<div class="sect1">
752<h2 id="_url_format">URL Format</h2>
753<div class="sectionbody">
754<div class="paragraph"><p>URLs for Git repositories accessed by HTTP use the standard HTTP
755URL syntax documented by RFC 1738, so they are of the form:</p></div>
756<div class="literalblock">
757<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]758<pre><code>http://&lt;host&gt;:&lt;port&gt;/&lt;path&gt;?&lt;searchpart&gt;</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]759</div></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]760<div class="paragraph"><p>Within this documentation the placeholder <code>$GIT_URL</code> will stand for
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]761the http:// repository URL entered by the end-user.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]762<div class="paragraph"><p>Servers SHOULD handle all requests to locations matching <code>$GIT_URL</code>, as
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]763both the "smart" and "dumb" HTTP protocols used by Git operate
764by appending additional path components onto the end of the user
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]765supplied <code>$GIT_URL</code> string.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]766<div class="paragraph"><p>An example of a dumb client requesting for a loose object:</p></div>
767<div class="literalblock">
768<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]769<pre><code>$GIT_URL: http://example.com:8080/git/repo.git
770URL request: http://example.com:8080/git/repo.git/objects/d0/49f6c27a2244e12041955e262a404c7faba355</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]771</div></div>
772<div class="paragraph"><p>An example of a smart request to a catch-all gateway:</p></div>
773<div class="literalblock">
774<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]775<pre><code>$GIT_URL: http://example.com/daemon.cgi?svc=git&amp;q=
776URL request: http://example.com/daemon.cgi?svc=git&amp;q=/info/refs&amp;service=git-receive-pack</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]777</div></div>
778<div class="paragraph"><p>An example of a request to a submodule:</p></div>
779<div class="literalblock">
780<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]781<pre><code>$GIT_URL: http://example.com/git/repo.git/path/submodule.git
782URL request: http://example.com/git/repo.git/path/submodule.git/info/refs</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]783</div></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]784<div class="paragraph"><p>Clients MUST strip a trailing <code>/</code>, if present, from the user supplied
785<code>$GIT_URL</code> string to prevent empty path tokens (<code>//</code>) from appearing
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]786in any URL sent to a server. Compatible clients MUST expand
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]787<code>$GIT_URL/info/refs</code> as <code>foo/info/refs</code> and not <code>foo//info/refs</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]788</div>
789</div>
790<div class="sect1">
791<h2 id="_authentication">Authentication</h2>
792<div class="sectionbody">
793<div class="paragraph"><p>Standard HTTP authentication is used if authentication is required
794to access a repository, and MAY be configured and enforced by the
795HTTP server software.</p></div>
796<div class="paragraph"><p>Because Git repositories are accessed by standard path components
797server administrators MAY use directory based permissions within
798their HTTP server to control repository access.</p></div>
Junio C Hamano38d02532014-06-26 21:48:50[diff] [blame]799<div class="paragraph"><p>Clients SHOULD support Basic authentication as described by RFC 2617.
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]800Servers SHOULD support Basic authentication by relying upon the
801HTTP server placed in front of the Git server software.</p></div>
802<div class="paragraph"><p>Servers SHOULD NOT require HTTP cookies for the purposes of
803authentication or access control.</p></div>
804<div class="paragraph"><p>Clients and servers MAY support other common forms of HTTP based
805authentication, such as Digest authentication.</p></div>
806</div>
807</div>
808<div class="sect1">
809<h2 id="_ssl">SSL</h2>
810<div class="sectionbody">
811<div class="paragraph"><p>Clients and servers SHOULD support SSL, particularly to protect
812passwords when relying on Basic HTTP authentication.</p></div>
813</div>
814</div>
815<div class="sect1">
816<h2 id="_session_state">Session State</h2>
817<div class="sectionbody">
818<div class="paragraph"><p>The Git over HTTP protocol (much like HTTP itself) is stateless
819from the perspective of the HTTP server side. All state MUST be
820retained and managed by the client process. This permits simple
821round-robin load-balancing on the server side, without needing to
822worry about state management.</p></div>
823<div class="paragraph"><p>Clients MUST NOT require state management on the server side in
824order to function correctly.</p></div>
825<div class="paragraph"><p>Servers MUST NOT require HTTP cookies in order to function correctly.
826Clients MAY store and forward HTTP cookies during request processing
827as described by RFC 2616 (HTTP/1.1). Servers SHOULD ignore any
828cookies sent by a client.</p></div>
829</div>
830</div>
831<div class="sect1">
832<h2 id="_general_request_processing">General Request Processing</h2>
833<div class="sectionbody">
834<div class="paragraph"><p>Except where noted, all standard HTTP behavior SHOULD be assumed
835by both client and server. This includes (but is not necessarily
836limited to):</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]837<div class="paragraph"><p>If there is no repository at <code>$GIT_URL</code>, or the resource pointed to by a
838location matching <code>$GIT_URL</code> does not exist, the server MUST NOT respond
839with <code>200 OK</code> response. A server SHOULD respond with
840<code>404 Not Found</code>, <code>410 Gone</code>, or any other suitable HTTP status code
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]841which does not imply the resource exists as requested.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]842<div class="paragraph"><p>If there is a repository at <code>$GIT_URL</code>, but access is not currently
843permitted, the server MUST respond with the <code>403 Forbidden</code> HTTP
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]844status code.</p></div>
845<div class="paragraph"><p>Servers SHOULD support both HTTP 1.0 and HTTP 1.1.
846Servers SHOULD support chunked encoding for both request and response
847bodies.</p></div>
848<div class="paragraph"><p>Clients SHOULD support both HTTP 1.0 and HTTP 1.1.
849Clients SHOULD support chunked encoding for both request and response
850bodies.</p></div>
851<div class="paragraph"><p>Servers MAY return ETag and/or Last-Modified headers.</p></div>
852<div class="paragraph"><p>Clients MAY revalidate cached entities by including If-Modified-Since
853and/or If-None-Match request headers.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]854<div class="paragraph"><p>Servers MAY return <code>304 Not Modified</code> if the relevant headers appear
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]855in the request and the entity has not changed. Clients MUST treat
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]856<code>304 Not Modified</code> identical to <code>200 OK</code> by reusing the cached entity.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]857<div class="paragraph"><p>Clients MAY reuse a cached entity without revalidation if the
858Cache-Control and/or Expires header permits caching. Clients and
859servers MUST follow RFC 2616 for cache controls.</p></div>
860</div>
861</div>
862<div class="sect1">
863<h2 id="_discovering_references">Discovering References</h2>
864<div class="sectionbody">
865<div class="paragraph"><p>All HTTP clients MUST begin either a fetch or a push exchange by
866discovering the references available on the remote repository.</p></div>
867<div class="sect2">
868<h3 id="_dumb_clients">Dumb Clients</h3>
869<div class="paragraph"><p>HTTP clients that only support the "dumb" protocol MUST discover
870references by making a request for the special info/refs file of
871the repository.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]872<div class="paragraph"><p>Dumb HTTP clients MUST make a <code>GET</code> request to <code>$GIT_URL/info/refs</code>,
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]873without any search/query parameters.</p></div>
874<div class="literalblock">
875<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]876<pre><code>C: GET $GIT_URL/info/refs HTTP/1.0</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]877</div></div>
878<div class="literalblock">
879<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]880<pre><code>S: 200 OK
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]881S:
882S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
883S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master
884S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]885S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]886</div></div>
887<div class="paragraph"><p>The Content-Type of the returned info/refs entity SHOULD be
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]888<code>text/plain; charset=utf-8</code>, but MAY be any content type.
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]889Clients MUST NOT attempt to validate the returned Content-Type.
890Dumb servers MUST NOT return a return type starting with
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]891<code>application/x-git-</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]892<div class="paragraph"><p>Cache-Control headers MAY be returned to disable caching of the
893returned entity.</p></div>
894<div class="paragraph"><p>When examining the response clients SHOULD only examine the HTTP
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]895status code. Valid responses are <code>200 OK</code>, or <code>304 Not Modified</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]896<div class="paragraph"><p>The returned content is a UNIX formatted text file describing
897each ref and its known value. The file SHOULD be sorted by name
898according to the C locale ordering. The file SHOULD NOT include
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]899the default ref named <code>HEAD</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]900<div class="literalblock">
901<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]902<pre><code>info_refs = *( ref_record )
903ref_record = any_ref / peeled_ref</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]904</div></div>
905<div class="literalblock">
906<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]907<pre><code>any_ref = obj-id HTAB refname LF
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]908peeled_ref = obj-id HTAB refname LF
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]909 obj-id HTAB refname "^{}" LF</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]910</div></div>
911</div>
912<div class="sect2">
913<h3 id="_smart_clients">Smart Clients</h3>
914<div class="paragraph"><p>HTTP clients that support the "smart" protocol (or both the
915"smart" and "dumb" protocols) MUST discover references by making
916a parameterized request for the info/refs file of the repository.</p></div>
917<div class="paragraph"><p>The request MUST contain exactly one query parameter,
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]918<code>service=$servicename</code>, where <code>$servicename</code> MUST be the service
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]919name the client wishes to contact to complete the operation.
920The request MUST NOT contain additional query parameters.</p></div>
921<div class="literalblock">
922<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]923<pre><code>C: GET $GIT_URL/info/refs?service=git-upload-pack HTTP/1.0</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]924</div></div>
925<div class="paragraph"><p>dumb server reply:</p></div>
926<div class="literalblock">
927<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]928<pre><code>S: 200 OK
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]929S:
930S: 95dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint
931S: d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master
932S: 2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]933S: a3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]934</div></div>
935<div class="paragraph"><p>smart server reply:</p></div>
936<div class="literalblock">
937<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]938<pre><code>S: 200 OK
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]939S: Content-Type: application/x-git-upload-pack-advertisement
940S: Cache-Control: no-cache
941S:
942S: 001e# service=git-upload-pack\n
943S: 004895dcfa3633004da0049d3d0fa03f80589cbcaf31 refs/heads/maint\0multi_ack\n
944S: 0042d049f6c27a2244e12041955e262a404c7faba355 refs/heads/master\n
945S: 003c2cb58b79488a98d2721cea644875a8dd0026b115 refs/tags/v1.0\n
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]946S: 003fa3c2e2402b99163d1d59756e5f207ae21cccba4c refs/tags/v1.0^{}\n</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]947</div></div>
948<div class="sect3">
949<h4 id="_dumb_server_response">Dumb Server Response</h4>
950<div class="paragraph"><p>Dumb servers MUST respond with the dumb server reply format.</p></div>
951<div class="paragraph"><p>See the prior section under dumb clients for a more detailed
952description of the dumb server response.</p></div>
953</div>
954<div class="sect3">
955<h4 id="_smart_server_response">Smart Server Response</h4>
956<div class="paragraph"><p>If the server does not recognize the requested service name, or the
957requested service name has been disabled by the server administrator,
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]958the server MUST respond with the <code>403 Forbidden</code> HTTP status code.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]959<div class="paragraph"><p>Otherwise, smart servers MUST respond with the smart server reply
960format for the requested service name.</p></div>
961<div class="paragraph"><p>Cache-Control headers SHOULD be used to disable caching of the
962returned entity.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]963<div class="paragraph"><p>The Content-Type MUST be <code>application/x-$servicename-advertisement</code>.
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]964Clients SHOULD fall back to the dumb protocol if another content
965type is returned. When falling back to the dumb protocol clients
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]966SHOULD NOT make an additional request to <code>$GIT_URL/info/refs</code>, but
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]967instead SHOULD use the response already in hand. Clients MUST NOT
968continue if they do not support the dumb protocol.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]969<div class="paragraph"><p>Clients MUST validate the status code is either <code>200 OK</code> or
970<code>304 Not Modified</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]971<div class="paragraph"><p>Clients MUST validate the first five bytes of the response entity
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]972matches the regex <code>^[0-9a-f]{4}#</code>. If this test fails, clients
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]973MUST NOT continue.</p></div>
974<div class="paragraph"><p>Clients MUST parse the entire response as a sequence of pkt-line
975records.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]976<div class="paragraph"><p>Clients MUST verify the first pkt-line is <code># service=$servicename</code>.
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]977Servers MUST set $servicename to be the request parameter value.
978Servers SHOULD include an LF at the end of this line.
979Clients MUST ignore an LF at the end of the line.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]980<div class="paragraph"><p>Servers MUST terminate the response with the magic <code>0000</code> end
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]981pkt-line marker.</p></div>
982<div class="paragraph"><p>The returned response is a pkt-line stream describing each ref and
983its known value. The stream SHOULD be sorted by name according to
984the C locale ordering. The stream SHOULD include the default ref
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]985named <code>HEAD</code> as the first ref. The stream MUST include capability
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]986declarations behind a NUL on the first ref.</p></div>
987<div class="literalblock">
988<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]989<pre><code>smart_reply = PKT-LINE("# service=$servicename" LF)
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]990 ref_list
991 "0000"
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]992ref_list = empty_list / non_empty_list</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]993</div></div>
994<div class="literalblock">
995<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]996<pre><code>empty_list = PKT-LINE(zero-id SP "capabilities^{}" NUL cap-list LF)</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]997</div></div>
998<div class="literalblock">
999<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1000<pre><code>non_empty_list = PKT-LINE(obj-id SP name NUL cap_list LF)
1001 *ref_record</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1002</div></div>
1003<div class="literalblock">
1004<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1005<pre><code>cap-list = capability *(SP capability)
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1006capability = 1*(LC_ALPHA / DIGIT / "-" / "_")
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1007LC_ALPHA = %x61-7A</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1008</div></div>
1009<div class="literalblock">
1010<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1011<pre><code>ref_record = any_ref / peeled_ref
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1012any_ref = PKT-LINE(obj-id SP name LF)
1013peeled_ref = PKT-LINE(obj-id SP name LF)
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1014 PKT-LINE(obj-id SP name "^{}" LF</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1015</div></div>
1016</div>
1017</div>
1018</div>
1019</div>
1020<div class="sect1">
1021<h2 id="_smart_service_git_upload_pack">Smart Service git-upload-pack</h2>
1022<div class="sectionbody">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1023<div class="paragraph"><p>This service reads from the repository pointed to by <code>$GIT_URL</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1024<div class="paragraph"><p>Clients MUST first perform ref discovery with
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1025<code>$GIT_URL/info/refs?service=git-upload-pack</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1026<div class="literalblock">
1027<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1028<pre><code>C: POST $GIT_URL/git-upload-pack HTTP/1.0
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1029C: Content-Type: application/x-git-upload-pack-request
1030C:
1031C: 0032want 0a53e9ddeaddad63ad106860237bbf53411d11a7\n
1032C: 0032have 441b40d833fdfa93eb2908e52742248faf0ee993\n
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1033C: 0000</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1034</div></div>
1035<div class="literalblock">
1036<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1037<pre><code>S: 200 OK
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1038S: Content-Type: application/x-git-upload-pack-result
1039S: Cache-Control: no-cache
1040S:
1041S: ....ACK %s, continue
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1042S: ....NAK</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1043</div></div>
1044<div class="paragraph"><p>Clients MUST NOT reuse or revalidate a cached response.
1045Servers MUST include sufficient Cache-Control headers
1046to prevent caching of the response.</p></div>
1047<div class="paragraph"><p>Servers SHOULD support all capabilities defined here.</p></div>
1048<div class="paragraph"><p>Clients MUST send at least one "want" command in the request body.
1049Clients MUST NOT reference an id in a "want" command which did not
1050appear in the response obtained through ref discovery unless the
Junio C Hamano85f1fde2015-06-01 20:37:32[diff] [blame^]1051server advertises capability <code>allow-tip-sha1-in-want</code> or
1052<code>allow-reachable-sha1-in-want</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1053<div class="literalblock">
1054<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1055<pre><code>compute_request = want_list
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1056 have_list
1057 request_end
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1058request_end = "0000" / "done"</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1059</div></div>
1060<div class="literalblock">
1061<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1062<pre><code>want_list = PKT-LINE(want NUL cap_list LF)
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1063 *(want_pkt)
1064want_pkt = PKT-LINE(want LF)
1065want = "want" SP id
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1066cap_list = *(SP capability) SP</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1067</div></div>
1068<div class="literalblock">
1069<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1070<pre><code>have_list = *PKT-LINE("have" SP id LF)</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1071</div></div>
1072<div class="paragraph"><p>TODO: Document this further.</p></div>
1073<div class="sect2">
1074<h3 id="_the_negotiation_algorithm">The Negotiation Algorithm</h3>
1075<div class="paragraph"><p>The computation to select the minimal pack proceeds as follows
1076(C = client, S = server):</p></div>
1077<div class="paragraph"><p><em>init step:</em></p></div>
1078<div class="paragraph"><p>C: Use ref discovery to obtain the advertised refs.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1079<div class="paragraph"><p>C: Place any object seen into set <code>advertised</code>.</p></div>
1080<div class="paragraph"><p>C: Build an empty set, <code>common</code>, to hold the objects that are later
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1081 determined to be on both ends.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1082<div class="paragraph"><p>C: Build a set, <code>want</code>, of the objects from <code>advertised</code> the client
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1083 wants to fetch, based on what it saw during ref discovery.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1084<div class="paragraph"><p>C: Start a queue, <code>c_pending</code>, ordered by commit time (popping newest
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1085 first). Add all client refs. When a commit is popped from
1086 the queue its parents SHOULD be automatically inserted back.
1087 Commits MUST only enter the queue once.</p></div>
1088<div class="paragraph"><p><em>one compute step:</em></p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1089<div class="paragraph"><p>C: Send one <code>$GIT_URL/git-upload-pack</code> request:</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1090<div class="literalblock">
1091<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1092<pre><code>C: 0032want &lt;want #1&gt;...............................
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1093C: 0032want &lt;want #2&gt;...............................
1094....
1095C: 0032have &lt;common #1&gt;.............................
1096C: 0032have &lt;common #2&gt;.............................
1097....
1098C: 0032have &lt;have #1&gt;...............................
1099C: 0032have &lt;have #2&gt;...............................
1100....
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1101C: 0000</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1102</div></div>
1103<div class="paragraph"><p>The stream is organized into "commands", with each command
Junio C Hamanoe1aeb5e2014-06-06 19:16:29[diff] [blame]1104appearing by itself in a pkt-line. Within a command line,
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1105the text leading up to the first space is the command name,
1106and the remainder of the line to the first LF is the value.
1107Command lines are terminated with an LF as the last byte of
1108the pkt-line value.</p></div>
1109<div class="paragraph"><p>Commands MUST appear in the following order, if they appear
1110at all in the request stream:</p></div>
1111<div class="ulist"><ul>
1112<li>
1113<p>
1114"want"
1115</p>
1116</li>
1117<li>
1118<p>
1119"have"
1120</p>
1121</li>
1122</ul></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1123<div class="paragraph"><p>The stream is terminated by a pkt-line flush (<code>0000</code>).</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1124<div class="paragraph"><p>A single "want" or "have" command MUST have one hex formatted
1125SHA-1 as its value. Multiple SHA-1s MUST be sent by sending
1126multiple commands.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1127<div class="paragraph"><p>The <code>have</code> list is created by popping the first 32 commits
1128from <code>c_pending</code>. Less can be supplied if <code>c_pending</code> empties.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1129<div class="paragraph"><p>If the client has sent 256 "have" commits and has not yet
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1130received one of those back from <code>s_common</code>, or the client has
1131emptied <code>c_pending</code> it SHOULD include a "done" command to let
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1132the server know it won&#8217;t proceed:</p></div>
1133<div class="literalblock">
1134<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1135<pre><code>C: 0009done</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1136</div></div>
1137<div class="paragraph"><p>S: Parse the git-upload-pack request:</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1138<div class="paragraph"><p>Verify all objects in <code>want</code> are directly reachable from refs.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1139<div class="paragraph"><p>The server MAY walk backwards through history or through
1140the reflog to permit slightly stale requests.</p></div>
1141<div class="paragraph"><p>If no "want" objects are received, send an error:
1142TODO: Define error if no "want" lines are requested.</p></div>
1143<div class="paragraph"><p>If any "want" object is not reachable, send an error:
1144TODO: Define error if an invalid "want" is requested.</p></div>
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1145<div class="paragraph"><p>Create an empty list, <code>s_common</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1146<div class="paragraph"><p>If "have" was sent:</p></div>
1147<div class="paragraph"><p>Loop through the objects in the order supplied by the client.</p></div>
1148<div class="paragraph"><p>For each object, if the server has the object reachable from
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1149a ref, add it to <code>s_common</code>. If a commit is added to <code>s_common</code>,
1150do not add any ancestors, even if they also appear in <code>have</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1151<div class="paragraph"><p>S: Send the git-upload-pack response:</p></div>
1152<div class="paragraph"><p>If the server has found a closed set of objects to pack or the
1153request ends with "done", it replies with the pack.
1154TODO: Document the pack based response</p></div>
1155<div class="literalblock">
1156<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1157<pre><code>S: PACK...</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1158</div></div>
1159<div class="paragraph"><p>The returned stream is the side-band-64k protocol supported
1160by the git-upload-pack service, and the pack is embedded into
1161stream 1. Progress messages from the server side MAY appear
1162in stream 2.</p></div>
1163<div class="paragraph"><p>Here a "closed set of objects" is defined to have at least
1164one path from every "want" to at least one "common" object.</p></div>
1165<div class="paragraph"><p>If the server needs more information, it replies with a
1166status continue response:
1167TODO: Document the non-pack response</p></div>
1168<div class="paragraph"><p>C: Parse the upload-pack response:
1169 TODO: Document parsing response</p></div>
1170<div class="paragraph"><p><em>Do another compute step.</em></p></div>
1171</div>
1172</div>
1173</div>
1174<div class="sect1">
1175<h2 id="_smart_service_git_receive_pack">Smart Service git-receive-pack</h2>
1176<div class="sectionbody">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1177<div class="paragraph"><p>This service reads from the repository pointed to by <code>$GIT_URL</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1178<div class="paragraph"><p>Clients MUST first perform ref discovery with
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1179<code>$GIT_URL/info/refs?service=git-receive-pack</code>.</p></div>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1180<div class="literalblock">
1181<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1182<pre><code>C: POST $GIT_URL/git-receive-pack HTTP/1.0
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1183C: Content-Type: application/x-git-receive-pack-request
1184C:
1185C: ....0a53e9ddeaddad63ad106860237bbf53411d11a7 441b40d833fdfa93eb2908e52742248faf0ee993 refs/heads/maint\0 report-status
1186C: 0000
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1187C: PACK....</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1188</div></div>
1189<div class="literalblock">
1190<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1191<pre><code>S: 200 OK
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1192S: Content-Type: application/x-git-receive-pack-result
1193S: Cache-Control: no-cache
1194S:
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1195S: ....</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1196</div></div>
1197<div class="paragraph"><p>Clients MUST NOT reuse or revalidate a cached response.
1198Servers MUST include sufficient Cache-Control headers
1199to prevent caching of the response.</p></div>
1200<div class="paragraph"><p>Servers SHOULD support all capabilities defined here.</p></div>
1201<div class="paragraph"><p>Clients MUST send at least one command in the request body.
1202Within the command portion of the request body clients SHOULD send
1203the id obtained through ref discovery as old_id.</p></div>
1204<div class="literalblock">
1205<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1206<pre><code>update_request = command_list
1207 "PACK" &lt;binary data&gt;</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1208</div></div>
1209<div class="literalblock">
1210<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1211<pre><code>command_list = PKT-LINE(command NUL cap_list LF)
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1212 *(command_pkt)
1213command_pkt = PKT-LINE(command LF)
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1214cap_list = *(SP capability) SP</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1215</div></div>
1216<div class="literalblock">
1217<div class="content">
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1218<pre><code>command = create / delete / update
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1219create = zero-id SP new_id SP name
1220delete = old_id SP zero-id SP name
Junio C Hamanoc14e6ad2014-10-31 20:25:53[diff] [blame]1221update = old_id SP new_id SP name</code></pre>
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1222</div></div>
1223<div class="paragraph"><p>TODO: Document this further.</p></div>
1224</div>
1225</div>
1226<div class="sect1">
1227<h2 id="_references">References</h2>
1228<div class="sectionbody">
1229<div class="paragraph"><p><a href="http://www.ietf.org/rfc/rfc1738.txt">RFC 1738: Uniform Resource Locators (URL)</a>
1230<a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616: Hypertext Transfer Protocol&#8201;&#8212;&#8201;HTTP/1.1</a>
1231link:technical/pack-protocol.html
1232link:technical/protocol-capabilities.html</p></div>
1233</div>
1234</div>
1235</div>
1236<div id="footnotes"><hr /></div>
1237<div id="footer">
1238<div id="footer-text">
Junio C Hamano85f1fde2015-06-01 20:37:32[diff] [blame^]1239Last updated 2015-06-01 13:36:36 PDT
Junio C Hamanoc5bd79e2014-01-27 21:31:26[diff] [blame]1240</div>
1241</div>
1242</body>
1243</html>