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