gitweb.html

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN"
   3     "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
   4 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
   5 <head>
   6 <meta http-equiv="Content-Type" content="application/xhtml+xml; charset=UTF-8" />
   7 <meta name="generator" content="AsciiDoc 10.2.0" />
   8 <title>gitweb(1)</title>
   9 <style type="text/css">
  10 /* Shared CSS for AsciiDoc xhtml11 and html5 backends */
  11
  12 /* Default font. */
  13 body {
  14   font-family: Georgia,serif;
  15 }
  16
  17 /* Title font. */
  18 h1, h2, h3, h4, h5, h6,
  19 div.title, caption.title,
  20 thead, p.table.header,
  21 #toctitle,
  22 #author, #revnumber, #revdate, #revremark,
  23 #footer {
  24   font-family: Arial,Helvetica,sans-serif;
  25 }
  26
  27 body {
  28   margin: 1em 5% 1em 5%;
  29 }
  30
  31 a {
  32   color: blue;
  33   text-decoration: underline;
  34 }
  35 a:visited {
  36   color: fuchsia;
  37 }
  38
  39 em {
  40   font-style: italic;
  41   color: navy;
  42 }
  43
  44 strong {
  45   font-weight: bold;
  46   color: #083194;
  47 }
  48
  49 h1, h2, h3, h4, h5, h6 {
  50   color: #527bbd;
  51   margin-top: 1.2em;
  52   margin-bottom: 0.5em;
  53   line-height: 1.3;
  54 }
  55
  56 h1, h2, h3 {
  57   border-bottom: 2px solid silver;
  58 }
  59 h2 {
  60   padding-top: 0.5em;
  61 }
  62 h3 {
  63   float: left;
  64 }
  65 h3 + * {
  66   clear: left;
  67 }
  68 h5 {
  69   font-size: 1.0em;
  70 }
  71
  72 div.sectionbody {
  73   margin-left: 0;
  74 }
  75
  76 hr {
  77   border: 1px solid silver;
  78 }
  79
  80 p {
  81   margin-top: 0.5em;
  82   margin-bottom: 0.5em;
  83 }
  84
  85 ul, ol, li > p {
  86   margin-top: 0;
  87 }
  88 ul > li     { color: #aaa; }
  89 ul > li > * { color: black; }
  90
  91 .monospaced, code, pre {
  92   font-family: "Courier New", Courier, monospace;
  93   font-size: inherit;
  94   color: navy;
  95   padding: 0;
  96   margin: 0;
  97 }
  98 pre {
  99   white-space: pre-wrap;
 100 }
 101
 102 #author {
 103   color: #527bbd;
 104   font-weight: bold;
 105   font-size: 1.1em;
 106 }
 107 #email {
 108 }
 109 #revnumber, #revdate, #revremark {
 110 }
 111
 112 #footer {
 113   font-size: small;
 114   border-top: 2px solid silver;
 115   padding-top: 0.5em;
 116   margin-top: 4.0em;
 117 }
 118 #footer-text {
 119   float: left;
 120   padding-bottom: 0.5em;
 121 }
 122 #footer-badges {
 123   float: right;
 124   padding-bottom: 0.5em;
 125 }
 126
 127 #preamble {
 128   margin-top: 1.5em;
 129   margin-bottom: 1.5em;
 130 }
 131 div.imageblock, div.exampleblock, div.verseblock,
 132 div.quoteblock, div.literalblock, div.listingblock, div.sidebarblock,
 133 div.admonitionblock {
 134   margin-top: 1.0em;
 135   margin-bottom: 1.5em;
 136 }
 137 div.admonitionblock {
 138   margin-top: 2.0em;
 139   margin-bottom: 2.0em;
 140   margin-right: 10%;
 141   color: #606060;
 142 }
 143
 144 div.content { /* Block element content. */
 145   padding: 0;
 146 }
 147
 148 /* Block element titles. */
 149 div.title, caption.title {
 150   color: #527bbd;
 151   font-weight: bold;
 152   text-align: left;
 153   margin-top: 1.0em;
 154   margin-bottom: 0.5em;
 155 }
 156 div.title + * {
 157   margin-top: 0;
 158 }
 159
 160 td div.title:first-child {
 161   margin-top: 0.0em;
 162 }
 163 div.content div.title:first-child {
 164   margin-top: 0.0em;
 165 }
 166 div.content + div.title {
 167   margin-top: 0.0em;
 168 }
 169
 170 div.sidebarblock > div.content {
 171   background: #ffffee;
 172   border: 1px solid #dddddd;
 173   border-left: 4px solid #f0f0f0;
 174   padding: 0.5em;
 175 }
 176
 177 div.listingblock > div.content {
 178   border: 1px solid #dddddd;
 179   border-left: 5px solid #f0f0f0;
 180   background: #f8f8f8;
 181   padding: 0.5em;
 182 }
 183
 184 div.quoteblock, div.verseblock {
 185   padding-left: 1.0em;
 186   margin-left: 1.0em;
 187   margin-right: 10%;
 188   border-left: 5px solid #f0f0f0;
 189   color: #888;
 190 }
 191
 192 div.quoteblock > div.attribution {
 193   padding-top: 0.5em;
 194   text-align: right;
 195 }
 196
 197 div.verseblock > pre.content {
 198   font-family: inherit;
 199   font-size: inherit;
 200 }
 201 div.verseblock > div.attribution {
 202   padding-top: 0.75em;
 203   text-align: left;
 204 }
 205 /* DEPRECATED: Pre version 8.2.7 verse style literal block. */
 206 div.verseblock + div.attribution {
 207   text-align: left;
 208 }
 209
 210 div.admonitionblock .icon {
 211   vertical-align: top;
 212   font-size: 1.1em;
 213   font-weight: bold;
 214   text-decoration: underline;
 215   color: #527bbd;
 216   padding-right: 0.5em;
 217 }
 218 div.admonitionblock td.content {
 219   padding-left: 0.5em;
 220   border-left: 3px solid #dddddd;
 221 }
 222
 223 div.exampleblock > div.content {
 224   border-left: 3px solid #dddddd;
 225   padding-left: 0.5em;
 226 }
 227
 228 div.imageblock div.content { padding-left: 0; }
 229 span.image img { border-style: none; vertical-align: text-bottom; }
 230 a.image:visited { color: white; }
 231
 232 dl {
 233   margin-top: 0.8em;
 234   margin-bottom: 0.8em;
 235 }
 236 dt {
 237   margin-top: 0.5em;
 238   margin-bottom: 0;
 239   font-style: normal;
 240   color: navy;
 241 }
 242 dd > *:first-child {
 243   margin-top: 0.1em;
 244 }
 245
 246 ul, ol {
 247     list-style-position: outside;
 248 }
 249 ol.arabic {
 250   list-style-type: decimal;
 251 }
 252 ol.loweralpha {
 253   list-style-type: lower-alpha;
 254 }
 255 ol.upperalpha {
 256   list-style-type: upper-alpha;
 257 }
 258 ol.lowerroman {
 259   list-style-type: lower-roman;
 260 }
 261 ol.upperroman {
 262   list-style-type: upper-roman;
 263 }
 264
 265 div.compact ul, div.compact ol,
 266 div.compact p, div.compact p,
 267 div.compact div, div.compact div {
 268   margin-top: 0.1em;
 269   margin-bottom: 0.1em;
 270 }
 271
 272 tfoot {
 273   font-weight: bold;
 274 }
 275 td > div.verse {
 276   white-space: pre;
 277 }
 278
 279 div.hdlist {
 280   margin-top: 0.8em;
 281   margin-bottom: 0.8em;
 282 }
 283 div.hdlist tr {
 284   padding-bottom: 15px;
 285 }
 286 dt.hdlist1.strong, td.hdlist1.strong {
 287   font-weight: bold;
 288 }
 289 td.hdlist1 {
 290   vertical-align: top;
 291   font-style: normal;
 292   padding-right: 0.8em;
 293   color: navy;
 294 }
 295 td.hdlist2 {
 296   vertical-align: top;
 297 }
 298 div.hdlist.compact tr {
 299   margin: 0;
 300   padding-bottom: 0;
 301 }
 302
 303 .comment {
 304   background: yellow;
 305 }
 306
 307 .footnote, .footnoteref {
 308   font-size: 0.8em;
 309 }
 310
 311 span.footnote, span.footnoteref {
 312   vertical-align: super;
 313 }
 314
 315 #footnotes {
 316   margin: 20px 0 20px 0;
 317   padding: 7px 0 0 0;
 318 }
 319
 320 #footnotes div.footnote {
 321   margin: 0 0 5px 0;
 322 }
 323
 324 #footnotes hr {
 325   border: none;
 326   border-top: 1px solid silver;
 327   height: 1px;
 328   text-align: left;
 329   margin-left: 0;
 330   width: 20%;
 331   min-width: 100px;
 332 }
 333
 334 div.colist td {
 335   padding-right: 0.5em;
 336   padding-bottom: 0.3em;
 337   vertical-align: top;
 338 }
 339 div.colist td img {
 340   margin-top: 0.3em;
 341 }
 342
 343 @media print {
 344   #footer-badges { display: none; }
 345 }
 346
 347 #toc {
 348   margin-bottom: 2.5em;
 349 }
 350
 351 #toctitle {
 352   color: #527bbd;
 353   font-size: 1.1em;
 354   font-weight: bold;
 355   margin-top: 1.0em;
 356   margin-bottom: 0.1em;
 357 }
 358
 359 div.toclevel0, div.toclevel1, div.toclevel2, div.toclevel3, div.toclevel4 {
 360   margin-top: 0;
 361   margin-bottom: 0;
 362 }
 363 div.toclevel2 {
 364   margin-left: 2em;
 365   font-size: 0.9em;
 366 }
 367 div.toclevel3 {
 368   margin-left: 4em;
 369   font-size: 0.9em;
 370 }
 371 div.toclevel4 {
 372   margin-left: 6em;
 373   font-size: 0.9em;
 374 }
 375
 376 span.aqua { color: aqua; }
 377 span.black { color: black; }
 378 span.blue { color: blue; }
 379 span.fuchsia { color: fuchsia; }
 380 span.gray { color: gray; }
 381 span.green { color: green; }
 382 span.lime { color: lime; }
 383 span.maroon { color: maroon; }
 384 span.navy { color: navy; }
 385 span.olive { color: olive; }
 386 span.purple { color: purple; }
 387 span.red { color: red; }
 388 span.silver { color: silver; }
 389 span.teal { color: teal; }
 390 span.white { color: white; }
 391 span.yellow { color: yellow; }
 392
 393 span.aqua-background { background: aqua; }
 394 span.black-background { background: black; }
 395 span.blue-background { background: blue; }
 396 span.fuchsia-background { background: fuchsia; }
 397 span.gray-background { background: gray; }
 398 span.green-background { background: green; }
 399 span.lime-background { background: lime; }
 400 span.maroon-background { background: maroon; }
 401 span.navy-background { background: navy; }
 402 span.olive-background { background: olive; }
 403 span.purple-background { background: purple; }
 404 span.red-background { background: red; }
 405 span.silver-background { background: silver; }
 406 span.teal-background { background: teal; }
 407 span.white-background { background: white; }
 408 span.yellow-background { background: yellow; }
 409
 410 span.big { font-size: 2em; }
 411 span.small { font-size: 0.6em; }
 412
 413 span.underline { text-decoration: underline; }
 414 span.overline { text-decoration: overline; }
 415 span.line-through { text-decoration: line-through; }
 416
 417 div.unbreakable { page-break-inside: avoid; }
 418
 419
 420 /*
 421  * xhtml11 specific
 422  *
 423  * */
 424
 425 div.tableblock {
 426   margin-top: 1.0em;
 427   margin-bottom: 1.5em;
 428 }
 429 div.tableblock > table {
 430   border: 3px solid #527bbd;
 431 }
 432 thead, p.table.header {
 433   font-weight: bold;
 434   color: #527bbd;
 435 }
 436 p.table {
 437   margin-top: 0;
 438 }
 439 /* Because the table frame attribute is overridden by CSS in most browsers. */
 440 div.tableblock > table[frame="void"] {
 441   border-style: none;
 442 }
 443 div.tableblock > table[frame="hsides"] {
 444   border-left-style: none;
 445   border-right-style: none;
 446 }
 447 div.tableblock > table[frame="vsides"] {
 448   border-top-style: none;
 449   border-bottom-style: none;
 450 }
 451
 452
 453 /*
 454  * html5 specific
 455  *
 456  * */
 457
 458 table.tableblock {
 459   margin-top: 1.0em;
 460   margin-bottom: 1.5em;
 461 }
 462 thead, p.tableblock.header {
 463   font-weight: bold;
 464   color: #527bbd;
 465 }
 466 p.tableblock {
 467   margin-top: 0;
 468 }
 469 table.tableblock {
 470   border-width: 3px;
 471   border-spacing: 0px;
 472   border-style: solid;
 473   border-color: #527bbd;
 474   border-collapse: collapse;
 475 }
 476 th.tableblock, td.tableblock {
 477   border-width: 1px;
 478   padding: 4px;
 479   border-style: solid;
 480   border-color: #527bbd;
 481 }
 482
 483 table.tableblock.frame-topbot {
 484   border-left-style: hidden;
 485   border-right-style: hidden;
 486 }
 487 table.tableblock.frame-sides {
 488   border-top-style: hidden;
 489   border-bottom-style: hidden;
 490 }
 491 table.tableblock.frame-none {
 492   border-style: hidden;
 493 }
 494
 495 th.tableblock.halign-left, td.tableblock.halign-left {
 496   text-align: left;
 497 }
 498 th.tableblock.halign-center, td.tableblock.halign-center {
 499   text-align: center;
 500 }
 501 th.tableblock.halign-right, td.tableblock.halign-right {
 502   text-align: right;
 503 }
 504
 505 th.tableblock.valign-top, td.tableblock.valign-top {
 506   vertical-align: top;
 507 }
 508 th.tableblock.valign-middle, td.tableblock.valign-middle {
 509   vertical-align: middle;
 510 }
 511 th.tableblock.valign-bottom, td.tableblock.valign-bottom {
 512   vertical-align: bottom;
 513 }
 514
 515
 516 /*
 517  * manpage specific
 518  *
 519  * */
 520
 521 body.manpage h1 {
 522   padding-top: 0.5em;
 523   padding-bottom: 0.5em;
 524   border-top: 2px solid silver;
 525   border-bottom: 2px solid silver;
 526 }
 527 body.manpage h2 {
 528   border-style: none;
 529 }
 530 body.manpage div.sectionbody {
 531   margin-left: 3em;
 532 }
 533
 534 @media print {
 535   body.manpage div#toc { display: none; }
 536 }
 537
 538
 539 </style>
 540 <script type="text/javascript">
 541 /*<![CDATA[*/
 542 var asciidoc = {  // Namespace.
 543
 544 /////////////////////////////////////////////////////////////////////
 545 // Table Of Contents generator
 546 /////////////////////////////////////////////////////////////////////
 547
 548 /* Author: Mihai Bazon, September 2002
 549  * http://students.infoiasi.ro/~mishoo
 550  *
 551  * Table Of Content generator
 552  * Version: 0.4
 553  *
 554  * Feel free to use this script under the terms of the GNU General Public
 555  * License, as long as you do not remove or alter this notice.
 556  */
 557
 558  /* modified by Troy D. Hanson, September 2006. License: GPL */
 559  /* modified by Stuart Rackham, 2006, 2009. License: GPL */
 560
 561 // toclevels = 1..4.
 562 toc: function (toclevels) {
 563
 564   function getText(el) {
 565     var text = "";
 566     for (var i = el.firstChild; i != null; i = i.nextSibling) {
 567       if (i.nodeType == 3 /* Node.TEXT_NODE */) // IE doesn't speak constants.
 568         text += i.data;
 569       else if (i.firstChild != null)
 570         text += getText(i);
 571     }
 572     return text;
 573   }
 574
 575   function TocEntry(el, text, toclevel) {
 576     this.element = el;
 577     this.text = text;
 578     this.toclevel = toclevel;
 579   }
 580
 581   function tocEntries(el, toclevels) {
 582     var result = new Array;
 583     var re = new RegExp('[hH]([1-'+(toclevels+1)+'])');
 584     // Function that scans the DOM tree for header elements (the DOM2
 585     // nodeIterator API would be a better technique but not supported by all
 586     // browsers).
 587     var iterate = function (el) {
 588       for (var i = el.firstChild; i != null; i = i.nextSibling) {
 589         if (i.nodeType == 1 /* Node.ELEMENT_NODE */) {
 590           var mo = re.exec(i.tagName);
 591           if (mo && (i.getAttribute("class") || i.getAttribute("className")) != "float") {
 592             result[result.length] = new TocEntry(i, getText(i), mo[1]-1);
 593           }
 594           iterate(i);
 595         }
 596       }
 597     }
 598     iterate(el);
 599     return result;
 600   }
 601
 602   var toc = document.getElementById("toc");
 603   if (!toc) {
 604     return;
 605   }
 606
 607   // Delete existing TOC entries in case we're reloading the TOC.
 608   var tocEntriesToRemove = [];
 609   var i;
 610   for (i = 0; i < toc.childNodes.length; i++) {
 611     var entry = toc.childNodes[i];
 612     if (entry.nodeName.toLowerCase() == 'div'
 613      && entry.getAttribute("class")
 614      && entry.getAttribute("class").match(/^toclevel/))
 615       tocEntriesToRemove.push(entry);
 616   }
 617   for (i = 0; i < tocEntriesToRemove.length; i++) {
 618     toc.removeChild(tocEntriesToRemove[i]);
 619   }
 620
 621   // Rebuild TOC entries.
 622   var entries = tocEntries(document.getElementById("content"), toclevels);
 623   for (var i = 0; i < entries.length; ++i) {
 624     var entry = entries[i];
 625     if (entry.element.id == "")
 626       entry.element.id = "_toc_" + i;
 627     var a = document.createElement("a");
 628     a.href = "#" + entry.element.id;
 629     a.appendChild(document.createTextNode(entry.text));
 630     var div = document.createElement("div");
 631     div.appendChild(a);
 632     div.className = "toclevel" + entry.toclevel;
 633     toc.appendChild(div);
 634   }
 635   if (entries.length == 0)
 636     toc.parentNode.removeChild(toc);
 637 },
 638
 639
 640 /////////////////////////////////////////////////////////////////////
 641 // Footnotes generator
 642 /////////////////////////////////////////////////////////////////////
 643
 644 /* Based on footnote generation code from:
 645  * http://www.brandspankingnew.net/archive/2005/07/format_footnote.html
 646  */
 647
 648 footnotes: function () {
 649   // Delete existing footnote entries in case we're reloading the footnodes.
 650   var i;
 651   var noteholder = document.getElementById("footnotes");
 652   if (!noteholder) {
 653     return;
 654   }
 655   var entriesToRemove = [];
 656   for (i = 0; i < noteholder.childNodes.length; i++) {
 657     var entry = noteholder.childNodes[i];
 658     if (entry.nodeName.toLowerCase() == 'div' && entry.getAttribute("class") == "footnote")
 659       entriesToRemove.push(entry);
 660   }
 661   for (i = 0; i < entriesToRemove.length; i++) {
 662     noteholder.removeChild(entriesToRemove[i]);
 663   }
 664
 665   // Rebuild footnote entries.
 666   var cont = document.getElementById("content");
 667   var spans = cont.getElementsByTagName("span");
 668   var refs = {};
 669   var n = 0;
 670   for (i=0; i<spans.length; i++) {
 671     if (spans[i].className == "footnote") {
 672       n++;
 673       var note = spans[i].getAttribute("data-note");
 674       if (!note) {
 675         // Use [\s\S] in place of . so multi-line matches work.
 676         // Because JavaScript has no s (dotall) regex flag.
 677         note = spans[i].innerHTML.match(/\s*\[([\s\S]*)]\s*/)[1];
 678         spans[i].innerHTML =
 679           "[<a id='_footnoteref_" + n + "' href='#_footnote_" + n +
 680           "' title='View footnote' class='footnote'>" + n + "</a>]";
 681         spans[i].setAttribute("data-note", note);
 682       }
 683       noteholder.innerHTML +=
 684         "<div class='footnote' id='_footnote_" + n + "'>" +
 685         "<a href='#_footnoteref_" + n + "' title='Return to text'>" +
 686         n + "</a>. " + note + "</div>";
 687       var id =spans[i].getAttribute("id");
 688       if (id != null) refs["#"+id] = n;
 689     }
 690   }
 691   if (n == 0)
 692     noteholder.parentNode.removeChild(noteholder);
 693   else {
 694     // Process footnoterefs.
 695     for (i=0; i<spans.length; i++) {
 696       if (spans[i].className == "footnoteref") {
 697         var href = spans[i].getElementsByTagName("a")[0].getAttribute("href");
 698         href = href.match(/#.*/)[0];  // Because IE return full URL.
 699         n = refs[href];
 700         spans[i].innerHTML =
 701           "[<a href='#_footnote_" + n +
 702           "' title='View footnote' class='footnote'>" + n + "</a>]";
 703       }
 704     }
 705   }
 706 },
 707
 708 install: function(toclevels) {
 709   var timerId;
 710
 711   function reinstall() {
 712     asciidoc.footnotes();
 713     if (toclevels) {
 714       asciidoc.toc(toclevels);
 715     }
 716   }
 717
 718   function reinstallAndRemoveTimer() {
 719     clearInterval(timerId);
 720     reinstall();
 721   }
 722
 723   timerId = setInterval(reinstall, 500);
 724   if (document.addEventListener)
 725     document.addEventListener("DOMContentLoaded", reinstallAndRemoveTimer, false);
 726   else
 727     window.onload = reinstallAndRemoveTimer;
 728 }
 729
 730 }
 731 asciidoc.install();
 732 /*]]>*/
 733 </script>
 734 </head>
 735 <body class="manpage">
 736 <div id="header">
 737 <h1>
 738 gitweb(1) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>gitweb -
 743    Git web interface (web frontend to Git repositories)
 744 </p>
 745 </div>
 746 </div>
 747 <div id="content">
 748 <div class="sect1">
 749 <h2 id="_synopsis">SYNOPSIS</h2>
 750 <div class="sectionbody">
 751 <div class="paragraph"><p>To get started with gitweb, run <a href="git-instaweb.html">git-instaweb(1)</a> from a Git repository.
 752 This will configure and start your web server, and run a web browser pointing to
 753 gitweb.</p></div>
 754 </div>
 755 </div>
 756 <div class="sect1">
 757 <h2 id="_description">DESCRIPTION</h2>
 758 <div class="sectionbody">
 759 <div class="paragraph"><p>Gitweb provides a web interface to Git repositories.  Its features include:</p></div>
 760 <div class="ulist"><ul>
 761 <li>
 762 <p>
 763 Viewing multiple Git repositories with common root.
 764 </p>
 765 </li>
 766 <li>
 767 <p>
 768 Browsing every revision of the repository.
 769 </p>
 770 </li>
 771 <li>
 772 <p>
 773 Viewing the contents of files in the repository at any revision.
 774 </p>
 775 </li>
 776 <li>
 777 <p>
 778 Viewing the revision log of branches, history of files and directories,
 779   seeing what was changed, when, and by whom.
 780 </p>
 781 </li>
 782 <li>
 783 <p>
 784 Viewing the blame/annotation details of any file (if enabled).
 785 </p>
 786 </li>
 787 <li>
 788 <p>
 789 Generating RSS and Atom feeds of commits, for any branch.
 790   The feeds are auto-discoverable in modern web browsers.
 791 </p>
 792 </li>
 793 <li>
 794 <p>
 795 Viewing everything that was changed in a revision, and stepping through
 796   revisions one at a time, viewing the history of the repository.
 797 </p>
 798 </li>
 799 <li>
 800 <p>
 801 Finding commits whose commit messages match a given search term.
 802 </p>
 803 </li>
 804 </ul></div>
 805 <div class="paragraph"><p>See <a href="https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/">https://repo.or.cz/w/git.git/tree/HEAD:/gitweb/</a> for gitweb source code,
 806 browsed using gitweb itself.</p></div>
 807 </div>
 808 </div>
 809 <div class="sect1">
 810 <h2 id="_configuration">CONFIGURATION</h2>
 811 <div class="sectionbody">
 812 <div class="paragraph"><p>Various aspects of gitweb&#8217;s behavior can be controlled through the configuration
 813 file <code>gitweb_config.perl</code> or <code>/etc/gitweb.conf</code>.  See the <a href="gitweb.conf.html">gitweb.conf(5)</a>
 814 for details.</p></div>
 815 <div class="sect2">
 816 <h3 id="_repositories">Repositories</h3>
 817 <div class="paragraph"><p>Gitweb can show information from one or more Git repositories.  These
 818 repositories have to be all on local filesystem, and have to share a common
 819 repository root, i.e. be all under a single parent repository (but see also
 820 the "Advanced web server setup" section, "Webserver configuration with multiple
 821 projects' root" subsection).</p></div>
 822 <div class="listingblock">
 823 <div class="content">
 824 <pre><code>our $projectroot = '/path/to/parent/directory';</code></pre>
 825 </div></div>
 826 <div class="paragraph"><p>The default value for <code>$projectroot</code> is <code>/pub/git</code>.  You can change it during
 827 building gitweb via the <code>GITWEB_PROJECTROOT</code> build configuration variable.</p></div>
 828 <div class="paragraph"><p>By default all Git repositories under <code>$projectroot</code> are visible and available
 829 to gitweb.  The list of projects is generated by default by scanning the
 830 <code>$projectroot</code> directory for Git repositories (for object databases to be
 831 more exact; gitweb is not interested in a working area, and is best suited
 832 to showing "bare" repositories).</p></div>
 833 <div class="paragraph"><p>The name of the repository in gitweb is the path to its <code>$GIT_DIR</code> (its object
 834 database) relative to <code>$projectroot</code>.  Therefore the repository $repo can be
 835 found at "$projectroot/$repo".</p></div>
 836 </div>
 837 <div class="sect2">
 838 <h3 id="_projects_list_file_format">Projects list file format</h3>
 839 <div class="paragraph"><p>Instead of having gitweb find repositories by scanning the filesystem
 840 starting from $projectroot, you can provide a pre-generated list of
 841 visible projects by setting <code>$projects_list</code> to point to a plain text
 842 file with a list of projects (with some additional info).</p></div>
 843 <div class="paragraph"><p>This file uses the following format:</p></div>
 844 <div class="ulist"><ul>
 845 <li>
 846 <p>
 847 One record (for project / repository) per line; does not support line
 848 continuation (newline escaping).
 849 </p>
 850 </li>
 851 <li>
 852 <p>
 853 Leading and trailing whitespace are ignored.
 854 </p>
 855 </li>
 856 <li>
 857 <p>
 858 Whitespace separated fields; any run of whitespace can be used as field
 859 separator (rules for Perl&#8217;s "<code>split(" ", $line)</code>").
 860 </p>
 861 </li>
 862 <li>
 863 <p>
 864 Fields use modified URI encoding, defined in RFC 3986, section 2.1
 865 (Percent-Encoding), or rather "Query string encoding" (see
 866 <a href="https://en.wikipedia.org/wiki/Query_string#URL_encoding">https://en.wikipedia.org/wiki/Query_string#URL_encoding</a>), the difference
 867 being that SP (" ") can be encoded as "&#43;" (and therefore "&#43;" has to be
 868 also percent-encoded).
 869 </p>
 870 <div class="paragraph"><p>Reserved characters are: "%" (used for encoding), "&#43;" (can be used to
 871 encode SPACE), all whitespace characters as defined in Perl, including SP,
 872 TAB and LF, (used to separate fields in a record).</p></div>
 873 </li>
 874 <li>
 875 <p>
 876 Currently recognized fields are:
 877 </p>
 878 <div class="dlist"><dl>
 879 <dt class="hdlist1">
 880 &lt;repository path&gt;
 881 </dt>
 882 <dd>
 883 <p>
 884         path to repository GIT_DIR, relative to <code>$projectroot</code>
 885 </p>
 886 </dd>
 887 <dt class="hdlist1">
 888 &lt;repository owner&gt;
 889 </dt>
 890 <dd>
 891 <p>
 892         displayed as repository owner, preferably full name, or email,
 893         or both
 894 </p>
 895 </dd>
 896 </dl></div>
 897 </li>
 898 </ul></div>
 899 <div class="paragraph"><p>You can generate the projects list index file using the project_index action
 900 (the <em>TXT</em> link on projects list page) directly from gitweb; see also
 901 "Generating projects list using gitweb" section below.</p></div>
 902 <div class="paragraph"><p>Example contents:</p></div>
 903 <div class="listingblock">
 904 <div class="content">
 905 <pre><code>foo.git       Joe+R+Hacker+&lt;joe@example.com&gt;
 906 foo/bar.git   O+W+Ner+&lt;owner@example.org&gt;</code></pre>
 907 </div></div>
 908 <div class="paragraph"><p>By default this file controls only which projects are <strong>visible</strong> on projects
 909 list page (note that entries that do not point to correctly recognized Git
 910 repositories won&#8217;t be displayed by gitweb).  Even if a project is not
 911 visible on projects list page, you can view it nevertheless by hand-crafting
 912 a gitweb URL.  By setting <code>$strict_export</code> configuration variable (see
 913 <a href="gitweb.conf.html">gitweb.conf(5)</a>) to true value you can allow viewing only of
 914 repositories also shown on the overview page (i.e. only projects explicitly
 915 listed in projects list file will be accessible).</p></div>
 916 </div>
 917 <div class="sect2">
 918 <h3 id="_generating_projects_list_using_gitweb">Generating projects list using gitweb</h3>
 919 <div class="paragraph"><p>We assume that GITWEB_CONFIG has its default Makefile value, namely
 920 <em>gitweb_config.perl</em>. Put the following in <em>gitweb_make_index.perl</em> file:</p></div>
 921 <div class="listingblock">
 922 <div class="content">
 923 <pre><code>read_config_file("gitweb_config.perl");
 924 $projects_list = $projectroot;</code></pre>
 925 </div></div>
 926 <div class="paragraph"><p>Then create the following script to get list of project in the format
 927 suitable for GITWEB_LIST build configuration variable (or
 928 <code>$projects_list</code> variable in gitweb config):</p></div>
 929 <div class="listingblock">
 930 <div class="content">
 931 <pre><code>#!/bin/sh
 932
 933 export GITWEB_CONFIG="gitweb_make_index.perl"
 934 export GATEWAY_INTERFACE="CGI/1.1"
 935 export HTTP_ACCEPT="*/*"
 936 export REQUEST_METHOD="GET"
 937 export QUERY_STRING="a=project_index"
 938
 939 perl -- /var/www/cgi-bin/gitweb.cgi</code></pre>
 940 </div></div>
 941 <div class="paragraph"><p>Run this script and save its output to a file.  This file could then be used
 942 as projects list file, which means that you can set <code>$projects_list</code> to its
 943 filename.</p></div>
 944 </div>
 945 <div class="sect2">
 946 <h3 id="_controlling_access_to_git_repositories">Controlling access to Git repositories</h3>
 947 <div class="paragraph"><p>By default all Git repositories under <code>$projectroot</code> are visible and
 948 available to gitweb.  You can however configure how gitweb controls access
 949 to repositories.</p></div>
 950 <div class="ulist"><ul>
 951 <li>
 952 <p>
 953 As described in "Projects list file format" section, you can control which
 954 projects are <strong>visible</strong> by selectively including repositories in projects
 955 list file, and setting <code>$projects_list</code> gitweb configuration variable to
 956 point to it.  With <code>$strict_export</code> set, projects list file can be used to
 957 control which repositories are <strong>available</strong> as well.
 958 </p>
 959 </li>
 960 <li>
 961 <p>
 962 You can configure gitweb to only list and allow viewing of the explicitly
 963 exported repositories, via <code>$export_ok</code> variable in gitweb config file; see
 964 <a href="gitweb.conf.html">gitweb.conf(5)</a> manpage.  If it evaluates to true, gitweb shows
 965 repositories only if this file named by <code>$export_ok</code> exists in its object
 966 database (if directory has the magic file named <code>$export_ok</code>).
 967 </p>
 968 <div class="paragraph"><p>For example <a href="git-daemon.html">git-daemon(1)</a> by default (unless <code>--export-all</code> option
 969 is used) allows pulling only for those repositories that have
 970 <em>git-daemon-export-ok</em> file.  Adding</p></div>
 971 <div class="listingblock">
 972 <div class="content">
 973 <pre><code>our $export_ok = "git-daemon-export-ok";</code></pre>
 974 </div></div>
 975 <div class="paragraph"><p>makes gitweb show and allow access only to those repositories that can be
 976 fetched from via <code>git://</code> protocol.</p></div>
 977 </li>
 978 <li>
 979 <p>
 980 Finally, it is possible to specify an arbitrary perl subroutine that will
 981 be called for each repository to determine if it can be exported.  The
 982 subroutine receives an absolute path to the project (repository) as its only
 983 parameter (i.e. "$projectroot/$project").
 984 </p>
 985 <div class="paragraph"><p>For example, if you use mod_perl to run the script, and have dumb
 986 HTTP protocol authentication configured for your repositories, you
 987 can use the following hook to allow access only if the user is
 988 authorized to read the files:</p></div>
 989 <div class="listingblock">
 990 <div class="content">
 991 <pre><code>$export_auth_hook = sub {
 992         use Apache2::SubRequest ();
 993         use Apache2::Const -compile =&gt; qw(HTTP_OK);
 994         my $path = "$_[0]/HEAD";
 995         my $r    = Apache2::RequestUtil-&gt;request;
 996         my $sub  = $r-&gt;lookup_file($path);
 997         return $sub-&gt;filename eq $path
 998             &amp;&amp; $sub-&gt;status == Apache2::Const::HTTP_OK;
 999 };</code></pre>
1000 </div></div>
1001 </li>
1002 </ul></div>
1003 </div>
1004 <div class="sect2">
1005 <h3 id="_per_repository_gitweb_configuration">Per-repository gitweb configuration</h3>
1006 <div class="paragraph"><p>You can configure individual repositories shown in gitweb by creating file
1007 in the <code>GIT_DIR</code> of Git repository, or by setting some repo configuration
1008 variable (in <code>GIT_DIR/config</code>, see <a href="git-config.html">git-config(1)</a>).</p></div>
1009 <div class="paragraph"><p>You can use the following files in repository:</p></div>
1010 <div class="dlist"><dl>
1011 <dt class="hdlist1">
1012 README.html
1013 </dt>
1014 <dd>
1015 <p>
1016         A html file (HTML fragment) which is included on the gitweb project
1017         "summary" page inside <code>&lt;div&gt;</code> block element. You can use it for longer
1018         description of a project, to provide links (for example to project&#8217;s
1019         homepage), etc. This is recognized only if XSS prevention is off
1020         (<code>$prevent_xss</code> is false, see <a href="gitweb.conf.html">gitweb.conf(5)</a>); a way to include
1021         a README safely when XSS prevention is on may be worked out in the
1022         future.
1023 </p>
1024 </dd>
1025 <dt class="hdlist1">
1026 description (or <code>gitweb.description</code>)
1027 </dt>
1028 <dd>
1029 <p>
1030         Short (shortened to <code>$projects_list_description_width</code> in the projects
1031         list page, which is 25 characters by default; see
1032         <a href="gitweb.conf.html">gitweb.conf(5)</a>) single line description of a project (of a
1033         repository).  Plain text file; HTML will be escaped.  By default set to
1034 </p>
1035 <div class="listingblock">
1036 <div class="content">
1037 <pre><code>Unnamed repository; edit this file to name it for gitweb.</code></pre>
1038 </div></div>
1039 <div class="paragraph"><p>from the template during repository creation, usually installed in
1040 <code>/usr/share/git-core/templates/</code>.  You can use the <code>gitweb.description</code> repo
1041 configuration variable, but the file takes precedence.</p></div>
1042 </dd>
1043 <dt class="hdlist1">
1044 category (or <code>gitweb.category</code>)
1045 </dt>
1046 <dd>
1047 <p>
1048         Singe line category of a project, used to group projects if
1049         <code>$projects_list_group_categories</code> is enabled.  By default (file and
1050         configuration variable absent), uncategorized projects are put in the
1051         <code>$project_list_default_category</code> category.  You can use the
1052         <code>gitweb.category</code> repo configuration variable, but the file takes
1053         precedence.
1054 </p>
1055 <div class="paragraph"><p>The configuration variables <code>$projects_list_group_categories</code> and
1056 <code>$project_list_default_category</code> are described in <a href="gitweb.conf.html">gitweb.conf(5)</a></p></div>
1057 </dd>
1058 <dt class="hdlist1">
1059 cloneurl (or multiple-valued <code>gitweb.url</code>)
1060 </dt>
1061 <dd>
1062 <p>
1063         File with repository URL (used for clone and fetch), one per line.
1064         Displayed in the project summary page. You can use multiple-valued
1065         <code>gitweb.url</code> repository configuration variable for that, but the file
1066         takes precedence.
1067 </p>
1068 <div class="paragraph"><p>This is per-repository enhancement / version of global prefix-based
1069 <code>@git_base_url_list</code> gitweb configuration variable (see
1070 <a href="gitweb.conf.html">gitweb.conf(5)</a>).</p></div>
1071 </dd>
1072 <dt class="hdlist1">
1073 gitweb.owner
1074 </dt>
1075 <dd>
1076 <p>
1077         You can use the <code>gitweb.owner</code> repository configuration variable to set
1078         repository&#8217;s owner.  It is displayed in the project list and summary
1079         page.
1080 </p>
1081 <div class="paragraph"><p>If it&#8217;s not set, filesystem directory&#8217;s owner is used (via GECOS field,
1082 i.e. real name field from <strong>getpwuid</strong>(3)) if <code>$projects_list</code> is unset
1083 (gitweb scans <code>$projectroot</code> for repositories); if <code>$projects_list</code>
1084 points to file with list of repositories, then project owner defaults to
1085 value from this file for given repository.</p></div>
1086 </dd>
1087 <dt class="hdlist1">
1088 various <code>gitweb.*</code> config variables (in config)
1089 </dt>
1090 <dd>
1091 <p>
1092         Read description of <code>%feature</code> hash for detailed list, and descriptions.
1093         See also "Configuring gitweb features" section in <a href="gitweb.conf.html">gitweb.conf(5)</a>
1094 </p>
1095 </dd>
1096 </dl></div>
1097 </div>
1098 </div>
1099 </div>
1100 <div class="sect1">
1101 <h2 id="_actions_and_urls">ACTIONS, AND URLS</h2>
1102 <div class="sectionbody">
1103 <div class="paragraph"><p>Gitweb can use path_info (component) based URLs, or it can pass all necessary
1104 information via query parameters.  The typical gitweb URLs are broken down in to
1105 five components:</p></div>
1106 <div class="listingblock">
1107 <div class="content">
1108 <pre><code>.../gitweb.cgi/&lt;repo&gt;/&lt;action&gt;/&lt;revision&gt;:/&lt;path&gt;?&lt;arguments&gt;</code></pre>
1109 </div></div>
1110 <div class="dlist"><dl>
1111 <dt class="hdlist1">
1112 repo
1113 </dt>
1114 <dd>
1115 <p>
1116         The repository the action will be performed on.
1117 </p>
1118 <div class="paragraph"><p>All actions except for those that list all available projects,
1119 in whatever form, require this parameter.</p></div>
1120 </dd>
1121 <dt class="hdlist1">
1122 action
1123 </dt>
1124 <dd>
1125 <p>
1126         The action that will be run.  Defaults to <em>projects_list</em> if repo
1127         is not set, and to <em>summary</em> otherwise.
1128 </p>
1129 </dd>
1130 <dt class="hdlist1">
1131 revision
1132 </dt>
1133 <dd>
1134 <p>
1135         Revision shown.  Defaults to HEAD.
1136 </p>
1137 </dd>
1138 <dt class="hdlist1">
1139 path
1140 </dt>
1141 <dd>
1142 <p>
1143         The path within the &lt;repository&gt; that the action is performed on,
1144         for those actions that require it.
1145 </p>
1146 </dd>
1147 <dt class="hdlist1">
1148 arguments
1149 </dt>
1150 <dd>
1151 <p>
1152         Any arguments that control the behaviour of the action.
1153 </p>
1154 </dd>
1155 </dl></div>
1156 <div class="paragraph"><p>Some actions require or allow to specify two revisions, and sometimes even two
1157 pathnames.  In most general form such path_info (component) based gitweb URL
1158 looks like this:</p></div>
1159 <div class="listingblock">
1160 <div class="content">
1161 <pre><code>.../gitweb.cgi/&lt;repo&gt;/&lt;action&gt;/&lt;revision-from&gt;:/&lt;path-from&gt;..&lt;revision-to&gt;:/&lt;path-to&gt;?&lt;arguments&gt;</code></pre>
1162 </div></div>
1163 <div class="paragraph"><p>Each action is implemented as a subroutine, and must be present in %actions
1164 hash.  Some actions are disabled by default, and must be turned on via feature
1165 mechanism.  For example to enable <em>blame</em> view add the following to gitweb
1166 configuration file:</p></div>
1167 <div class="listingblock">
1168 <div class="content">
1169 <pre><code>$feature{'blame'}{'default'} = [1];</code></pre>
1170 </div></div>
1171 <div class="sect2">
1172 <h3 id="_actions">Actions:</h3>
1173 <div class="paragraph"><p>The standard actions are:</p></div>
1174 <div class="dlist"><dl>
1175 <dt class="hdlist1">
1176 project_list
1177 </dt>
1178 <dd>
1179 <p>
1180         Lists the available Git repositories.  This is the default command if no
1181         repository is specified in the URL.
1182 </p>
1183 </dd>
1184 <dt class="hdlist1">
1185 summary
1186 </dt>
1187 <dd>
1188 <p>
1189         Displays summary about given repository.  This is the default command if
1190         no action is specified in URL, and only repository is specified.
1191 </p>
1192 </dd>
1193 <dt class="hdlist1">
1194 heads
1195 </dt>
1196 <dt class="hdlist1">
1197 remotes
1198 </dt>
1199 <dd>
1200 <p>
1201         Lists all local or all remote-tracking branches in given repository.
1202 </p>
1203 <div class="paragraph"><p>The latter is not available by default, unless configured.</p></div>
1204 </dd>
1205 <dt class="hdlist1">
1206 tags
1207 </dt>
1208 <dd>
1209 <p>
1210         List all tags (lightweight and annotated) in given repository.
1211 </p>
1212 </dd>
1213 <dt class="hdlist1">
1214 blob
1215 </dt>
1216 <dt class="hdlist1">
1217 tree
1218 </dt>
1219 <dd>
1220 <p>
1221         Shows the files and directories in a given repository path, at given
1222         revision.  This is default command if no action is specified in the URL,
1223         and path is given.
1224 </p>
1225 </dd>
1226 <dt class="hdlist1">
1227 blob_plain
1228 </dt>
1229 <dd>
1230 <p>
1231         Returns the raw data for the file in given repository, at given path and
1232         revision.  Links to this action are marked <em>raw</em>.
1233 </p>
1234 </dd>
1235 <dt class="hdlist1">
1236 blobdiff
1237 </dt>
1238 <dd>
1239 <p>
1240         Shows the difference between two revisions of the same file.
1241 </p>
1242 </dd>
1243 <dt class="hdlist1">
1244 blame
1245 </dt>
1246 <dt class="hdlist1">
1247 blame_incremental
1248 </dt>
1249 <dd>
1250 <p>
1251         Shows the blame (also called annotation) information for a file. On a
1252         per line basis it shows the revision in which that line was last changed
1253         and the user that committed the change.  The incremental version (which
1254         if configured is used automatically when JavaScript is enabled) uses
1255         Ajax to incrementally add blame info to the contents of given file.
1256 </p>
1257 <div class="paragraph"><p>This action is disabled by default for performance reasons.</p></div>
1258 </dd>
1259 <dt class="hdlist1">
1260 commit
1261 </dt>
1262 <dt class="hdlist1">
1263 commitdiff
1264 </dt>
1265 <dd>
1266 <p>
1267         Shows information about a specific commit in a repository.  The <em>commit</em>
1268         view shows information about commit in more detail, the <em>commitdiff</em>
1269         action shows changeset for given commit.
1270 </p>
1271 </dd>
1272 <dt class="hdlist1">
1273 patch
1274 </dt>
1275 <dd>
1276 <p>
1277         Returns the commit in plain text mail format, suitable for applying with
1278         <a href="git-am.html">git-am(1)</a>.
1279 </p>
1280 </dd>
1281 <dt class="hdlist1">
1282 tag
1283 </dt>
1284 <dd>
1285 <p>
1286         Display specific annotated tag (tag object).
1287 </p>
1288 </dd>
1289 <dt class="hdlist1">
1290 log
1291 </dt>
1292 <dt class="hdlist1">
1293 shortlog
1294 </dt>
1295 <dd>
1296 <p>
1297         Shows log information (commit message or just commit subject) for a
1298         given branch (starting from given revision).
1299 </p>
1300 <div class="paragraph"><p>The <em>shortlog</em> view is more compact; it shows one commit per line.</p></div>
1301 </dd>
1302 <dt class="hdlist1">
1303 history
1304 </dt>
1305 <dd>
1306 <p>
1307         Shows history of the file or directory in a given repository path,
1308         starting from given revision (defaults to HEAD, i.e. default branch).
1309 </p>
1310 <div class="paragraph"><p>This view is similar to <em>shortlog</em> view.</p></div>
1311 </dd>
1312 <dt class="hdlist1">
1313 rss
1314 </dt>
1315 <dt class="hdlist1">
1316 atom
1317 </dt>
1318 <dd>
1319 <p>
1320         Generates an RSS (or Atom) feed of changes to repository.
1321 </p>
1322 </dd>
1323 </dl></div>
1324 </div>
1325 </div>
1326 </div>
1327 <div class="sect1">
1328 <h2 id="_webserver_configuration">WEBSERVER CONFIGURATION</h2>
1329 <div class="sectionbody">
1330 <div class="paragraph"><p>This section explains how to configure some common webservers to run gitweb. In
1331 all cases, <code>/path/to/gitweb</code> in the examples is the directory you ran installed
1332 gitweb in, and contains <code>gitweb_config.perl</code>.</p></div>
1333 <div class="paragraph"><p>If you&#8217;ve configured a web server that isn&#8217;t listed here for gitweb, please send
1334 in the instructions so they can be included in a future release.</p></div>
1335 <div class="sect2">
1336 <h3 id="_apache_as_cgi">Apache as CGI</h3>
1337 <div class="paragraph"><p>Apache must be configured to support CGI scripts in the directory in
1338 which gitweb is installed.  Let&#8217;s assume that it is <code>/var/www/cgi-bin</code>
1339 directory.</p></div>
1340 <div class="listingblock">
1341 <div class="content">
1342 <pre><code>ScriptAlias /cgi-bin/ "/var/www/cgi-bin/"
1343
1344 &lt;Directory "/var/www/cgi-bin"&gt;
1345     Options Indexes FollowSymlinks ExecCGI
1346     AllowOverride None
1347     Order allow,deny
1348     Allow from all
1349 &lt;/Directory&gt;</code></pre>
1350 </div></div>
1351 <div class="paragraph"><p>With that configuration the full path to browse repositories would be:</p></div>
1352 <div class="literalblock">
1353 <div class="content">
1354 <pre><code>http://server/cgi-bin/gitweb.cgi</code></pre>
1355 </div></div>
1356 </div>
1357 <div class="sect2">
1358 <h3 id="_apache_with_mod_perl_via_modperl_registry">Apache with mod_perl, via ModPerl::Registry</h3>
1359 <div class="paragraph"><p>You can use mod_perl with gitweb.  You must install Apache::Registry
1360 (for mod_perl 1.x) or ModPerl::Registry (for mod_perl 2.x) to enable
1361 this support.</p></div>
1362 <div class="paragraph"><p>Assuming that gitweb is installed to <code>/var/www/perl</code>, the following
1363 Apache configuration (for mod_perl 2.x) is suitable.</p></div>
1364 <div class="listingblock">
1365 <div class="content">
1366 <pre><code>Alias /perl "/var/www/perl"
1367
1368 &lt;Directory "/var/www/perl"&gt;
1369     SetHandler perl-script
1370     PerlResponseHandler ModPerl::Registry
1371     PerlOptions +ParseHeaders
1372     Options Indexes FollowSymlinks +ExecCGI
1373     AllowOverride None
1374     Order allow,deny
1375     Allow from all
1376 &lt;/Directory&gt;</code></pre>
1377 </div></div>
1378 <div class="paragraph"><p>With that configuration the full path to browse repositories would be:</p></div>
1379 <div class="literalblock">
1380 <div class="content">
1381 <pre><code>http://server/perl/gitweb.cgi</code></pre>
1382 </div></div>
1383 </div>
1384 <div class="sect2">
1385 <h3 id="_apache_with_fastcgi">Apache with FastCGI</h3>
1386 <div class="paragraph"><p>Gitweb works with Apache and FastCGI.  First you need to rename, copy
1387 or symlink gitweb.cgi to gitweb.fcgi.  Let&#8217;s assume that gitweb is
1388 installed in <code>/usr/share/gitweb</code> directory.  The following Apache
1389 configuration is suitable (UNTESTED!)</p></div>
1390 <div class="listingblock">
1391 <div class="content">
1392 <pre><code>FastCgiServer /usr/share/gitweb/gitweb.cgi
1393 ScriptAlias /gitweb /usr/share/gitweb/gitweb.cgi
1394
1395 Alias /gitweb/static /usr/share/gitweb/static
1396 &lt;Directory /usr/share/gitweb/static&gt;
1397     SetHandler default-handler
1398 &lt;/Directory&gt;</code></pre>
1399 </div></div>
1400 <div class="paragraph"><p>With that configuration the full path to browse repositories would be:</p></div>
1401 <div class="literalblock">
1402 <div class="content">
1403 <pre><code>http://server/gitweb</code></pre>
1404 </div></div>
1405 </div>
1406 </div>
1407 </div>
1408 <div class="sect1">
1409 <h2 id="_advanced_web_server_setup">ADVANCED WEB SERVER SETUP</h2>
1410 <div class="sectionbody">
1411 <div class="paragraph"><p>All of those examples use request rewriting, and need <code>mod_rewrite</code>
1412 (or equivalent; examples below are written for Apache).</p></div>
1413 <div class="sect2">
1414 <h3 id="_single_url_for_gitweb_and_for_fetching">Single URL for gitweb and for fetching</h3>
1415 <div class="paragraph"><p>If you want to have one URL for both gitweb and your <code>http://</code>
1416 repositories, you can configure Apache like this:</p></div>
1417 <div class="listingblock">
1418 <div class="content">
1419 <pre><code>&lt;VirtualHost *:80&gt;
1420     ServerName    git.example.org
1421     DocumentRoot  /pub/git
1422     SetEnv        GITWEB_CONFIG   /etc/gitweb.conf
1423
1424     # turning on mod rewrite
1425     RewriteEngine on
1426
1427     # make the front page an internal rewrite to the gitweb script
1428     RewriteRule ^/$  /cgi-bin/gitweb.cgi
1429
1430     # make access for "dumb clients" work
1431     RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \
1432                 /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]
1433 &lt;/VirtualHost&gt;</code></pre>
1434 </div></div>
1435 <div class="paragraph"><p>The above configuration expects your public repositories to live under
1436 <code>/pub/git</code> and will serve them as <code>http://git.domain.org/dir-under-pub-git</code>,
1437 both as clonable Git URL and as browsable gitweb interface.  If you then
1438 start your <a href="git-daemon.html">git-daemon(1)</a> with <code>--base-path=/pub/git --export-all</code>
1439 then you can even use the <code>git://</code> URL with exactly the same path.</p></div>
1440 <div class="paragraph"><p>Setting the environment variable <code>GITWEB_CONFIG</code> will tell gitweb to use the
1441 named file (i.e. in this example <code>/etc/gitweb.conf</code>) as a configuration for
1442 gitweb.  You don&#8217;t really need it in above example; it is required only if
1443 your configuration file is in different place than built-in (during
1444 compiling gitweb) <em>gitweb_config.perl</em> or <code>/etc/gitweb.conf</code>.  See
1445 <a href="gitweb.conf.html">gitweb.conf(5)</a> for details, especially information about precedence
1446 rules.</p></div>
1447 <div class="paragraph"><p>If you use the rewrite rules from the example you <strong>might</strong> also need
1448 something like the following in your gitweb configuration file
1449 (<code>/etc/gitweb.conf</code> following example):</p></div>
1450 <div class="listingblock">
1451 <div class="content">
1452 <pre><code>@stylesheets = ("/some/absolute/path/gitweb.css");
1453 $my_uri    = "/";
1454 $home_link = "/";
1455 $per_request_config = 1;</code></pre>
1456 </div></div>
1457 <div class="paragraph"><p>Nowadays though gitweb should create HTML base tag when needed (to set base
1458 URI for relative links), so it should work automatically.</p></div>
1459 </div>
1460 <div class="sect2">
1461 <h3 id="_webserver_configuration_with_multiple_projects_root">Webserver configuration with multiple projects' root</h3>
1462 <div class="paragraph"><p>If you want to use gitweb with several project roots you can edit your
1463 Apache virtual host and gitweb configuration files in the following way.</p></div>
1464 <div class="paragraph"><p>The virtual host configuration (in Apache configuration file) should look
1465 like this:</p></div>
1466 <div class="listingblock">
1467 <div class="content">
1468 <pre><code>&lt;VirtualHost *:80&gt;
1469     ServerName    git.example.org
1470     DocumentRoot  /pub/git
1471     SetEnv        GITWEB_CONFIG  /etc/gitweb.conf
1472
1473     # turning on mod rewrite
1474     RewriteEngine on
1475
1476     # make the front page an internal rewrite to the gitweb script
1477     RewriteRule ^/$  /cgi-bin/gitweb.cgi  [QSA,L,PT]
1478
1479     # look for a public_git directory in unix users' home
1480     # http://git.example.org/~&lt;user&gt;/
1481     RewriteRule ^/\~([^\/]+)(/|/gitweb.cgi)?$   /cgi-bin/gitweb.cgi \
1482                 [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
1483
1484     # http://git.example.org/+&lt;user&gt;/
1485     #RewriteRule ^/\+([^\/]+)(/|/gitweb.cgi)?$  /cgi-bin/gitweb.cgi \
1486                  [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
1487
1488     # http://git.example.org/user/&lt;user&gt;/
1489     #RewriteRule ^/user/([^\/]+)/(gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
1490                  [QSA,E=GITWEB_PROJECTROOT:/home/$1/public_git/,L,PT]
1491
1492     # defined list of project roots
1493     RewriteRule ^/scm(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
1494                 [QSA,E=GITWEB_PROJECTROOT:/pub/scm/,L,PT]
1495     RewriteRule ^/var(/|/gitweb.cgi)?$ /cgi-bin/gitweb.cgi \
1496                 [QSA,E=GITWEB_PROJECTROOT:/var/git/,L,PT]
1497
1498     # make access for "dumb clients" work
1499     RewriteRule ^/(.*\.git/(?!/?(HEAD|info|objects|refs)).*)?$ \
1500                 /cgi-bin/gitweb.cgi%{REQUEST_URI}  [L,PT]
1501 &lt;/VirtualHost&gt;</code></pre>
1502 </div></div>
1503 <div class="paragraph"><p>Here actual project root is passed to gitweb via <code>GITWEB_PROJECT_ROOT</code>
1504 environment variable from a web server, so you need to put the following
1505 line in gitweb configuration file (<code>/etc/gitweb.conf</code> in above example):</p></div>
1506 <div class="listingblock">
1507 <div class="content">
1508 <pre><code>$projectroot = $ENV{'GITWEB_PROJECTROOT'} || "/pub/git";</code></pre>
1509 </div></div>
1510 <div class="paragraph"><p><strong>Note</strong> that this requires to be set for each request, so either
1511 <code>$per_request_config</code> must be false, or the above must be put in code
1512 referenced by <code>$per_request_config</code>;</p></div>
1513 <div class="paragraph"><p>These configurations enable two things. First, each unix user (<code>&lt;user&gt;</code>) of
1514 the server will be able to browse through gitweb Git repositories found in
1515 <code>~/public_git/</code> with the following url:</p></div>
1516 <div class="literalblock">
1517 <div class="content">
1518 <pre><code>http://git.example.org/~&lt;user&gt;/</code></pre>
1519 </div></div>
1520 <div class="paragraph"><p>If you do not want this feature on your server just remove the second
1521 rewrite rule.</p></div>
1522 <div class="paragraph"><p>If you already use &#8216;mod_userdir` in your virtual host or you don&#8217;t want to
1523 use the '~&#8217; as first character, just comment or remove the second rewrite
1524 rule, and uncomment one of the following according to what you want.</p></div>
1525 <div class="paragraph"><p>Second, repositories found in <code>/pub/scm/</code> and <code>/var/git/</code> will be accessible
1526 through <code>http://git.example.org/scm/</code> and <code>http://git.example.org/var/</code>.
1527 You can add as many project roots as you want by adding rewrite rules like
1528 the third and the fourth.</p></div>
1529 </div>
1530 <div class="sect2">
1531 <h3 id="_path_info_usage">PATH_INFO usage</h3>
1532 <div class="paragraph"><p>If you enable PATH_INFO usage in gitweb by putting</p></div>
1533 <div class="listingblock">
1534 <div class="content">
1535 <pre><code>$feature{'pathinfo'}{'default'} = [1];</code></pre>
1536 </div></div>
1537 <div class="paragraph"><p>in your gitweb configuration file, it is possible to set up your server so
1538 that it consumes and produces URLs in the form</p></div>
1539 <div class="literalblock">
1540 <div class="content">
1541 <pre><code>http://git.example.com/project.git/shortlog/sometag</code></pre>
1542 </div></div>
1543 <div class="paragraph"><p>i.e. without <em>gitweb.cgi</em> part, by using a configuration such as the
1544 following.  This configuration assumes that <code>/var/www/gitweb</code> is the
1545 DocumentRoot of your webserver, contains the gitweb.cgi script and
1546 complementary static files (stylesheet, favicon, JavaScript):</p></div>
1547 <div class="listingblock">
1548 <div class="content">
1549 <pre><code>&lt;VirtualHost *:80&gt;
1550         ServerAlias git.example.com
1551
1552         DocumentRoot /var/www/gitweb
1553
1554         &lt;Directory /var/www/gitweb&gt;
1555                 Options ExecCGI
1556                 AddHandler cgi-script cgi
1557
1558                 DirectoryIndex gitweb.cgi
1559
1560                 RewriteEngine On
1561                 RewriteCond %{REQUEST_FILENAME} !-f
1562                 RewriteCond %{REQUEST_FILENAME} !-d
1563                 RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
1564         &lt;/Directory&gt;
1565 &lt;/VirtualHost&gt;</code></pre>
1566 </div></div>
1567 <div class="paragraph"><p>The rewrite rule guarantees that existing static files will be properly
1568 served, whereas any other URL will be passed to gitweb as PATH_INFO
1569 parameter.</p></div>
1570 <div class="paragraph"><p><strong>Notice</strong> that in this case you don&#8217;t need special settings for
1571 <code>@stylesheets</code>, <code>$my_uri</code> and <code>$home_link</code>, but you lose "dumb client"
1572 access to your project .git dirs (described in "Single URL for gitweb and
1573 for fetching" section).  A possible workaround for the latter is the
1574 following: in your project root dir (e.g. <code>/pub/git</code>) have the projects
1575 named <strong>without</strong> a .git extension (e.g. <code>/pub/git/project</code> instead of
1576 <code>/pub/git/project.git</code>) and configure Apache as follows:</p></div>
1577 <div class="listingblock">
1578 <div class="content">
1579 <pre><code>&lt;VirtualHost *:80&gt;
1580         ServerAlias git.example.com
1581
1582         DocumentRoot /var/www/gitweb
1583
1584         AliasMatch ^(/.*?)(\.git)(/.*)?$ /pub/git$1$3
1585         &lt;Directory /var/www/gitweb&gt;
1586                 Options ExecCGI
1587                 AddHandler cgi-script cgi
1588
1589                 DirectoryIndex gitweb.cgi
1590
1591                 RewriteEngine On
1592                 RewriteCond %{REQUEST_FILENAME} !-f
1593                 RewriteCond %{REQUEST_FILENAME} !-d
1594                 RewriteRule ^.* /gitweb.cgi/$0 [L,PT]
1595         &lt;/Directory&gt;
1596 &lt;/VirtualHost&gt;</code></pre>
1597 </div></div>
1598 <div class="paragraph"><p>The additional AliasMatch makes it so that</p></div>
1599 <div class="literalblock">
1600 <div class="content">
1601 <pre><code>http://git.example.com/project.git</code></pre>
1602 </div></div>
1603 <div class="paragraph"><p>will give raw access to the project&#8217;s Git dir (so that the project can be
1604 cloned), while</p></div>
1605 <div class="literalblock">
1606 <div class="content">
1607 <pre><code>http://git.example.com/project</code></pre>
1608 </div></div>
1609 <div class="paragraph"><p>will provide human-friendly gitweb access.</p></div>
1610 <div class="paragraph"><p>This solution is not 100% bulletproof, in the sense that if some project has
1611 a named ref (branch, tag) starting with <code>git/</code>, then paths such as</p></div>
1612 <div class="literalblock">
1613 <div class="content">
1614 <pre><code>http://git.example.com/project/command/abranch..git/abranch</code></pre>
1615 </div></div>
1616 <div class="paragraph"><p>will fail with a 404 error.</p></div>
1617 </div>
1618 </div>
1619 </div>
1620 <div class="sect1">
1621 <h2 id="_bugs">BUGS</h2>
1622 <div class="sectionbody">
1623 <div class="paragraph"><p>Please report any bugs or feature requests to <a href="mailto:git@vger.kernel.org">git@vger.kernel.org</a>,
1624 putting "gitweb" in the subject of email.</p></div>
1625 </div>
1626 </div>
1627 <div class="sect1">
1628 <h2 id="_see_also">SEE ALSO</h2>
1629 <div class="sectionbody">
1630 <div class="paragraph"><p><a href="gitweb.conf.html">gitweb.conf(5)</a>, <a href="git-instaweb.html">git-instaweb(1)</a></p></div>
1631 <div class="paragraph"><p><code>gitweb/README</code>, <code>gitweb/INSTALL</code></p></div>
1632 </div>
1633 </div>
1634 <div class="sect1">
1635 <h2 id="_git">GIT</h2>
1636 <div class="sectionbody">
1637 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
1638 </div>
1639 </div>
1640 </div>
1641 <div id="footnotes"><hr /></div>
1642 <div id="footer">
1643 <div id="footer-text">
1644 Last updated
1645  2024-02-08 15:45:59 PST
1646 </div>
1647 </div>
1648 </body>
1649 </html>