gitweb.conf.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.conf(5)</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.conf(5) Manual Page
 739 </h1>
 740 <h2>NAME</h2>
 741 <div class="sectionbody">
 742 <p>gitweb.conf -
 743    Gitweb (Git web interface) configuration file
 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>/etc/gitweb.conf, /etc/gitweb-common.conf, $GITWEBDIR/gitweb_config.perl</p></div>
 752 </div>
 753 </div>
 754 <div class="sect1">
 755 <h2 id="_description">DESCRIPTION</h2>
 756 <div class="sectionbody">
 757 <div class="paragraph"><p>The gitweb CGI script for viewing Git repositories over the web uses a
 758 perl script fragment as its configuration file.  You can set variables
 759 using "<code>our $variable = value</code>"; text from a "#" character until the
 760 end of a line is ignored.  See <strong>perlsyn</strong>(1) for details.</p></div>
 761 <div class="paragraph"><p>An example:</p></div>
 762 <div class="listingblock">
 763 <div class="content">
 764 <pre><code># gitweb configuration file for http://git.example.org
 765 #
 766 our $projectroot = "/srv/git"; # FHS recommendation
 767 our $site_name = 'Example.org &gt;&gt; Repos';</code></pre>
 768 </div></div>
 769 <div class="paragraph"><p>The configuration file is used to override the default settings that
 770 were built into gitweb at the time the <em>gitweb.cgi</em> script was generated.</p></div>
 771 <div class="paragraph"><p>While one could just alter the configuration settings in the gitweb
 772 CGI itself, those changes would be lost upon upgrade.  Configuration
 773 settings might also be placed into a file in the same directory as the
 774 CGI script with the default name <em>gitweb_config.perl</em>&#8201;&#8212;&#8201;allowing
 775 one to have multiple gitweb instances with different configurations by
 776 the use of symlinks.</p></div>
 777 <div class="paragraph"><p>Note that some configuration can be controlled on per-repository rather than
 778 gitweb-wide basis: see "Per-repository gitweb configuration" subsection on
 779 <a href="gitweb.html">gitweb(1)</a> manpage.</p></div>
 780 </div>
 781 </div>
 782 <div class="sect1">
 783 <h2 id="_discussion">DISCUSSION</h2>
 784 <div class="sectionbody">
 785 <div class="paragraph"><p>Gitweb reads configuration data from the following sources in the
 786 following order:</p></div>
 787 <div class="ulist"><ul>
 788 <li>
 789 <p>
 790 built-in values (some set during build stage),
 791 </p>
 792 </li>
 793 <li>
 794 <p>
 795 common system-wide configuration file (defaults to
 796    <code>/etc/gitweb-common.conf</code>),
 797 </p>
 798 </li>
 799 <li>
 800 <p>
 801 either per-instance configuration file (defaults to <em>gitweb_config.perl</em>
 802    in the same directory as the installed gitweb), or if it does not exist
 803    then fallback system-wide configuration file (defaults to <code>/etc/gitweb.conf</code>).
 804 </p>
 805 </li>
 806 </ul></div>
 807 <div class="paragraph"><p>Values obtained in later configuration files override values obtained earlier
 808 in the above sequence.</p></div>
 809 <div class="paragraph"><p>Locations of the common system-wide configuration file, the fallback
 810 system-wide configuration file and the per-instance configuration file
 811 are defined at compile time using build-time Makefile configuration
 812 variables, respectively <code>GITWEB_CONFIG_COMMON</code>, <code>GITWEB_CONFIG_SYSTEM</code>
 813 and <code>GITWEB_CONFIG</code>.</p></div>
 814 <div class="paragraph"><p>You can also override locations of gitweb configuration files during
 815 runtime by setting the following environment variables:
 816 <code>GITWEB_CONFIG_COMMON</code>, <code>GITWEB_CONFIG_SYSTEM</code> and <code>GITWEB_CONFIG</code>
 817 to a non-empty value.</p></div>
 818 <div class="paragraph"><p>The syntax of the configuration files is that of Perl, since these files are
 819 handled by sourcing them as fragments of Perl code (the language that
 820 gitweb itself is written in). Variables are typically set using the
 821 <code>our</code> qualifier (as in "<code>our $variable = &lt;value&gt;;</code>") to avoid syntax
 822 errors if a new version of gitweb no longer uses a variable and therefore
 823 stops declaring it.</p></div>
 824 <div class="paragraph"><p>You can include other configuration file using read_config_file()
 825 subroutine.  For example, one might want to put gitweb configuration
 826 related to access control for viewing repositories via Gitolite (one
 827 of Git repository management tools) in a separate file, e.g. in
 828 <code>/etc/gitweb-gitolite.conf</code>.  To include it, put</p></div>
 829 <div class="listingblock">
 830 <div class="content">
 831 <pre><code>read_config_file("/etc/gitweb-gitolite.conf");</code></pre>
 832 </div></div>
 833 <div class="paragraph"><p>somewhere in gitweb configuration file used, e.g. in per-installation
 834 gitweb configuration file.  Note that read_config_file() checks itself
 835 that the file it reads exists, and does nothing if it is not found.
 836 It also handles errors in included file.</p></div>
 837 <div class="paragraph"><p>The default configuration with no configuration file at all may work
 838 perfectly well for some installations.  Still, a configuration file is
 839 useful for customizing or tweaking the behavior of gitweb in many ways, and
 840 some optional features will not be present unless explicitly enabled using
 841 the configurable <code>%features</code> variable (see also "Configuring gitweb
 842 features" section below).</p></div>
 843 </div>
 844 </div>
 845 <div class="sect1">
 846 <h2 id="_configuration_variables">CONFIGURATION VARIABLES</h2>
 847 <div class="sectionbody">
 848 <div class="paragraph"><p>Some configuration variables have their default values (embedded in the CGI
 849 script) set during building gitweb&#8201;&#8212;&#8201;if that is the case, this fact is put
 850 in their description.  See gitweb&#8217;s <em>INSTALL</em> file for instructions on building
 851 and installing gitweb.</p></div>
 852 <div class="sect2">
 853 <h3 id="_location_of_repositories">Location of repositories</h3>
 854 <div class="paragraph"><p>The configuration variables described below control how gitweb finds
 855 Git repositories, and how repositories are displayed and accessed.</p></div>
 856 <div class="paragraph"><p>See also "Repositories" and later subsections in <a href="gitweb.html">gitweb(1)</a> manpage.</p></div>
 857 <div class="dlist"><dl>
 858 <dt class="hdlist1">
 859 $projectroot
 860 </dt>
 861 <dd>
 862 <p>
 863         Absolute filesystem path which will be prepended to project path;
 864         the path to repository is <code>$projectroot/$project</code>.  Set to
 865         <code>$GITWEB_PROJECTROOT</code> during installation.  This variable has to be
 866         set correctly for gitweb to find repositories.
 867 </p>
 868 <div class="paragraph"><p>For example, if <code>$projectroot</code> is set to "/srv/git" by putting the following
 869 in gitweb config file:</p></div>
 870 <div class="listingblock">
 871 <div class="content">
 872 <pre><code>our $projectroot = "/srv/git";</code></pre>
 873 </div></div>
 874 <div class="paragraph"><p>then</p></div>
 875 <div class="listingblock">
 876 <div class="content">
 877 <pre><code>http://git.example.com/gitweb.cgi?p=foo/bar.git</code></pre>
 878 </div></div>
 879 <div class="paragraph"><p>and its path_info based equivalent</p></div>
 880 <div class="listingblock">
 881 <div class="content">
 882 <pre><code>http://git.example.com/gitweb.cgi/foo/bar.git</code></pre>
 883 </div></div>
 884 <div class="paragraph"><p>will map to the path <code>/srv/git/foo/bar.git</code> on the filesystem.</p></div>
 885 </dd>
 886 <dt class="hdlist1">
 887 $projects_list
 888 </dt>
 889 <dd>
 890 <p>
 891         Name of a plain text file listing projects, or a name of directory
 892         to be scanned for projects.
 893 </p>
 894 <div class="paragraph"><p>Project list files should list one project per line, with each line
 895 having the following format</p></div>
 896 <div class="listingblock">
 897 <div class="content">
 898 <pre><code>&lt;URI-encoded filesystem path to repository&gt; SP &lt;URI-encoded repository owner&gt;</code></pre>
 899 </div></div>
 900 <div class="paragraph"><p>The default value of this variable is determined by the <code>GITWEB_LIST</code>
 901 makefile variable at installation time.  If this variable is empty, gitweb
 902 will fall back to scanning the <code>$projectroot</code> directory for repositories.</p></div>
 903 </dd>
 904 <dt class="hdlist1">
 905 $project_maxdepth
 906 </dt>
 907 <dd>
 908 <p>
 909         If <code>$projects_list</code> variable is unset, gitweb will recursively
 910         scan filesystem for Git repositories.  The <code>$project_maxdepth</code>
 911         is used to limit traversing depth, relative to <code>$projectroot</code>
 912         (starting point); it means that directories which are further
 913         from <code>$projectroot</code> than <code>$project_maxdepth</code> will be skipped.
 914 </p>
 915 <div class="paragraph"><p>It is purely performance optimization, originally intended for MacOS X,
 916 where recursive directory traversal is slow.  Gitweb follows symbolic
 917 links, but it detects cycles, ignoring any duplicate files and directories.</p></div>
 918 <div class="paragraph"><p>The default value of this variable is determined by the build-time
 919 configuration variable <code>GITWEB_PROJECT_MAXDEPTH</code>, which defaults to
 920 2007.</p></div>
 921 </dd>
 922 <dt class="hdlist1">
 923 $export_ok
 924 </dt>
 925 <dd>
 926 <p>
 927         Show repository only if this file exists (in repository).  Only
 928         effective if this variable evaluates to true.  Can be set when
 929         building gitweb by setting <code>GITWEB_EXPORT_OK</code>.  This path is
 930         relative to <code>GIT_DIR</code>.  git-daemon[1] uses <em>git-daemon-export-ok</em>,
 931         unless started with <code>--export-all</code>.  By default this variable is
 932         not set, which means that this feature is turned off.
 933 </p>
 934 </dd>
 935 <dt class="hdlist1">
 936 $export_auth_hook
 937 </dt>
 938 <dd>
 939 <p>
 940         Function used to determine which repositories should be shown.
 941         This subroutine should take one parameter, the full path to
 942         a project, and if it returns true, that project will be included
 943         in the projects list and can be accessed through gitweb as long
 944         as it fulfills the other requirements described by $export_ok,
 945         $projects_list, and $projects_maxdepth.  Example:
 946 </p>
 947 <div class="listingblock">
 948 <div class="content">
 949 <pre><code>our $export_auth_hook = sub { return -e "$_[0]/git-daemon-export-ok"; };</code></pre>
 950 </div></div>
 951 <div class="paragraph"><p>though the above might be done by using <code>$export_ok</code> instead</p></div>
 952 <div class="listingblock">
 953 <div class="content">
 954 <pre><code>our $export_ok = "git-daemon-export-ok";</code></pre>
 955 </div></div>
 956 <div class="paragraph"><p>If not set (default), it means that this feature is disabled.</p></div>
 957 <div class="paragraph"><p>See also more involved example in "Controlling access to Git repositories"
 958 subsection on <a href="gitweb.html">gitweb(1)</a> manpage.</p></div>
 959 </dd>
 960 <dt class="hdlist1">
 961 $strict_export
 962 </dt>
 963 <dd>
 964 <p>
 965         Only allow viewing of repositories also shown on the overview page.
 966         This for example makes <code>$export_ok</code> file decide if repository is
 967         available and not only if it is shown.  If <code>$projects_list</code> points to
 968         file with list of project, only those repositories listed would be
 969         available for gitweb.  Can be set during building gitweb via
 970         <code>GITWEB_STRICT_EXPORT</code>.  By default this variable is not set, which
 971         means that you can directly access those repositories that are hidden
 972         from projects list page (e.g. the are not listed in the $projects_list
 973         file).
 974 </p>
 975 </dd>
 976 </dl></div>
 977 </div>
 978 <div class="sect2">
 979 <h3 id="_finding_files">Finding files</h3>
 980 <div class="paragraph"><p>The following configuration variables tell gitweb where to find files.
 981 The values of these variables are paths on the filesystem.</p></div>
 982 <div class="dlist"><dl>
 983 <dt class="hdlist1">
 984 $GIT
 985 </dt>
 986 <dd>
 987 <p>
 988         Core git executable to use.  By default set to <code>$GIT_BINDIR/git</code>, which
 989         in turn is by default set to <code>$(bindir)/git</code>.  If you use Git installed
 990         from a binary package, you should usually set this to "/usr/bin/git".
 991         This can just be "git" if your web server has a sensible PATH; from
 992         security point of view it is better to use absolute path to git binary.
 993         If you have multiple Git versions installed it can be used to choose
 994         which one to use.  Must be (correctly) set for gitweb to be able to
 995         work.
 996 </p>
 997 </dd>
 998 <dt class="hdlist1">
 999 $mimetypes_file
1000 </dt>
1001 <dd>
1002 <p>
1003         File to use for (filename extension based) guessing of MIME types before
1004         trying <code>/etc/mime.types</code>.  <strong>NOTE</strong> that this path, if relative, is taken
1005         as relative to the current Git repository, not to CGI script.  If unset,
1006         only <code>/etc/mime.types</code> is used (if present on filesystem).  If no mimetypes
1007         file is found, mimetype guessing based on extension of file is disabled.
1008         Unset by default.
1009 </p>
1010 </dd>
1011 <dt class="hdlist1">
1012 $highlight_bin
1013 </dt>
1014 <dd>
1015 <p>
1016         Path to the highlight executable to use (it must be the one from
1017         <a href="http://andre-simon.de/zip/download.php">http://andre-simon.de/zip/download.php</a> due to assumptions about parameters and output).
1018         By default set to <em>highlight</em>; set it to full path to highlight
1019         executable if it is not installed on your web server&#8217;s PATH.
1020         Note that <em>highlight</em> feature must be set for gitweb to actually
1021         use syntax highlighting.
1022 </p>
1023 <div class="paragraph"><p><strong>NOTE</strong>: for a file to be highlighted, its syntax type must be detected
1024 and that syntax must be supported by "highlight".  The default syntax
1025 detection is minimal, and there are many supported syntax types with no
1026 detection by default.  There are three options for adding syntax
1027 detection.  The first and second priority are <code>%highlight_basename</code> and
1028 <code>%highlight_ext</code>, which detect based on basename (the full filename, for
1029 example "Makefile") and extension (for example "sh").  The keys of these
1030 hashes are the basename and extension, respectively, and the value for a
1031 given key is the name of the syntax to be passed via <code>--syntax &lt;syntax&gt;</code>
1032 to "highlight".  The last priority is the "highlight" configuration of
1033 <code>Shebang</code> regular expressions to detect the language based on the first
1034 line in the file, (for example, matching the line "#!/bin/bash").  See
1035 the highlight documentation and the default config at
1036 /etc/highlight/filetypes.conf for more details.</p></div>
1037 <div class="paragraph"><p>For example if repositories you are hosting use "phtml" extension for
1038 PHP files, and you want to have correct syntax-highlighting for those
1039 files, you can add the following to gitweb configuration:</p></div>
1040 <div class="listingblock">
1041 <div class="content">
1042 <pre><code>our %highlight_ext;
1043 $highlight_ext{'phtml'} = 'php';</code></pre>
1044 </div></div>
1045 </dd>
1046 </dl></div>
1047 </div>
1048 <div class="sect2">
1049 <h3 id="_links_and_their_targets">Links and their targets</h3>
1050 <div class="paragraph"><p>The configuration variables described below configure some of gitweb links:
1051 their target and their look (text or image), and where to find page
1052 prerequisites (stylesheet, favicon, images, scripts).  Usually they are left
1053 at their default values, with the possible exception of <code>@stylesheets</code>
1054 variable.</p></div>
1055 <div class="dlist"><dl>
1056 <dt class="hdlist1">
1057 @stylesheets
1058 </dt>
1059 <dd>
1060 <p>
1061         List of URIs of stylesheets (relative to the base URI of a page). You
1062         might specify more than one stylesheet, for example to use "gitweb.css"
1063         as base with site specific modifications in a separate stylesheet
1064         to make it easier to upgrade gitweb.  For example, you can add
1065         a <code>site</code> stylesheet by putting
1066 </p>
1067 <div class="listingblock">
1068 <div class="content">
1069 <pre><code>push @stylesheets, "gitweb-site.css";</code></pre>
1070 </div></div>
1071 <div class="paragraph"><p>in the gitweb config file.  Those values that are relative paths are
1072 relative to base URI of gitweb.</p></div>
1073 <div class="paragraph"><p>This list should contain the URI of gitweb&#8217;s standard stylesheet.  The default
1074 URI of gitweb stylesheet can be set at build time using the <code>GITWEB_CSS</code>
1075 makefile variable.  Its default value is <code>static/gitweb.css</code>
1076 (or <code>static/gitweb.min.css</code> if the <code>CSSMIN</code> variable is defined,
1077 i.e. if CSS minifier is used during build).</p></div>
1078 <div class="paragraph"><p><strong>Note</strong>: there is also a legacy <code>$stylesheet</code> configuration variable, which was
1079 used by older gitweb.  If <code>$stylesheet</code> variable is defined, only CSS stylesheet
1080 given by this variable is used by gitweb.</p></div>
1081 </dd>
1082 <dt class="hdlist1">
1083 $logo
1084 </dt>
1085 <dd>
1086 <p>
1087         Points to the location where you put <em>git-logo.png</em> on your web
1088         server, or to be more the generic URI of logo, 72x27 size).  This image
1089         is displayed in the top right corner of each gitweb page and used as
1090         a logo for the Atom feed.  Relative to the base URI of gitweb (as a path).
1091         Can be adjusted when building gitweb using <code>GITWEB_LOGO</code> variable
1092         By default set to <code>static/git-logo.png</code>.
1093 </p>
1094 </dd>
1095 <dt class="hdlist1">
1096 $favicon
1097 </dt>
1098 <dd>
1099 <p>
1100         Points to the location where you put <em>git-favicon.png</em> on your web
1101         server, or to be more the generic URI of favicon, which will be served
1102         as "image/png" type.  Web browsers that support favicons (website icons)
1103         may display them in the browser&#8217;s URL bar and next to the site name in
1104         bookmarks.  Relative to the base URI of gitweb.  Can be adjusted at
1105         build time using <code>GITWEB_FAVICON</code> variable.
1106         By default set to <code>static/git-favicon.png</code>.
1107 </p>
1108 </dd>
1109 <dt class="hdlist1">
1110 $javascript
1111 </dt>
1112 <dd>
1113 <p>
1114         Points to the location where you put <em>gitweb.js</em> on your web server,
1115         or to be more generic the URI of JavaScript code used by gitweb.
1116         Relative to the base URI of gitweb.  Can be set at build time using
1117         the <code>GITWEB_JS</code> build-time configuration variable.
1118 </p>
1119 <div class="paragraph"><p>The default value is either <code>static/gitweb.js</code>, or <code>static/gitweb.min.js</code> if
1120 the <code>JSMIN</code> build variable was defined, i.e. if JavaScript minifier was used
1121 at build time.  <strong>Note</strong> that this single file is generated from multiple
1122 individual JavaScript "modules".</p></div>
1123 </dd>
1124 <dt class="hdlist1">
1125 $home_link
1126 </dt>
1127 <dd>
1128 <p>
1129         Target of the home link on the top of all pages (the first part of view
1130         "breadcrumbs").  By default it is set to the absolute URI of a current page
1131         (to the value of <code>$my_uri</code> variable, or to "/" if <code>$my_uri</code> is undefined
1132         or is an empty string).
1133 </p>
1134 </dd>
1135 <dt class="hdlist1">
1136 $home_link_str
1137 </dt>
1138 <dd>
1139 <p>
1140         Label for the "home link" at the top of all pages, leading to <code>$home_link</code>
1141         (usually the main gitweb page, which contains the projects list).  It is
1142         used as the first component of gitweb&#8217;s "breadcrumb trail":
1143         <code>&lt;home link&gt; / &lt;project&gt; / &lt;action&gt;</code>.  Can be set at build time using
1144         the <code>GITWEB_HOME_LINK_STR</code> variable.  By default it is set to "projects",
1145         as this link leads to the list of projects.  Another popular choice is to
1146         set it to the name of site.  Note that it is treated as raw HTML so it
1147         should not be set from untrusted sources.
1148 </p>
1149 </dd>
1150 <dt class="hdlist1">
1151 @extra_breadcrumbs
1152 </dt>
1153 <dd>
1154 <p>
1155         Additional links to be added to the start of the breadcrumb trail before
1156         the home link, to pages that are logically "above" the gitweb projects
1157         list, such as the organization and department which host the gitweb
1158         server. Each element of the list is a reference to an array, in which
1159         element 0 is the link text (equivalent to <code>$home_link_str</code>) and element
1160         1 is the target URL (equivalent to <code>$home_link</code>).
1161 </p>
1162 <div class="paragraph"><p>For example, the following setting produces a breadcrumb trail like
1163 "home / dev / projects / &#8230;" where "projects" is the home link.</p></div>
1164 <div class="listingblock">
1165 <div class="content">
1166 <pre><code>    our @extra_breadcrumbs = (
1167       [ 'home' =&gt; 'https://www.example.org/' ],
1168       [ 'dev'  =&gt; 'https://dev.example.org/' ],
1169     );</code></pre>
1170 </div></div>
1171 </dd>
1172 <dt class="hdlist1">
1173 $logo_url
1174 </dt>
1175 <dt class="hdlist1">
1176 $logo_label
1177 </dt>
1178 <dd>
1179 <p>
1180         URI and label (title) for the Git logo link (or your site logo,
1181         if you chose to use different logo image). By default, these both
1182         refer to Git homepage, <a href="https://git-scm.com">https://git-scm.com</a>; in the past, they pointed
1183         to Git documentation at <a href="https://www.kernel.org">https://www.kernel.org</a>.
1184 </p>
1185 </dd>
1186 </dl></div>
1187 </div>
1188 <div class="sect2">
1189 <h3 id="_changing_gitweb_8217_s_look">Changing gitweb&#8217;s look</h3>
1190 <div class="paragraph"><p>You can adjust how pages generated by gitweb look using the variables described
1191 below.  You can change the site name, add common headers and footers for all
1192 pages, and add a description of this gitweb installation on its main page
1193 (which is the projects list page), etc.</p></div>
1194 <div class="dlist"><dl>
1195 <dt class="hdlist1">
1196 $site_name
1197 </dt>
1198 <dd>
1199 <p>
1200         Name of your site or organization, to appear in page titles.  Set it
1201         to something descriptive for clearer bookmarks etc.  If this variable
1202         is not set or is, then gitweb uses the value of the <code>SERVER_NAME</code>
1203         <code>CGI</code> environment variable, setting site name to "$SERVER_NAME Git",
1204         or "Untitled Git" if this variable is not set (e.g. if running gitweb
1205         as standalone script).
1206 </p>
1207 <div class="paragraph"><p>Can be set using the <code>GITWEB_SITENAME</code> at build time.  Unset by default.</p></div>
1208 </dd>
1209 <dt class="hdlist1">
1210 $site_html_head_string
1211 </dt>
1212 <dd>
1213 <p>
1214         HTML snippet to be included in the &lt;head&gt; section of each page.
1215         Can be set using <code>GITWEB_SITE_HTML_HEAD_STRING</code> at build time.
1216         No default value.
1217 </p>
1218 </dd>
1219 <dt class="hdlist1">
1220 $site_header
1221 </dt>
1222 <dd>
1223 <p>
1224         Name of a file with HTML to be included at the top of each page.
1225         Relative to the directory containing the <em>gitweb.cgi</em> script.
1226         Can be set using <code>GITWEB_SITE_HEADER</code> at build time.  No default
1227         value.
1228 </p>
1229 </dd>
1230 <dt class="hdlist1">
1231 $site_footer
1232 </dt>
1233 <dd>
1234 <p>
1235         Name of a file with HTML to be included at the bottom of each page.
1236         Relative to the directory containing the <em>gitweb.cgi</em> script.
1237         Can be set using <code>GITWEB_SITE_FOOTER</code> at build time.  No default
1238         value.
1239 </p>
1240 </dd>
1241 <dt class="hdlist1">
1242 $home_text
1243 </dt>
1244 <dd>
1245 <p>
1246         Name of a HTML file which, if it exists, is included on the
1247         gitweb projects overview page ("projects_list" view).  Relative to
1248         the directory containing the gitweb.cgi script.  Default value
1249         can be adjusted during build time using <code>GITWEB_HOMETEXT</code> variable.
1250         By default set to <em>indextext.html</em>.
1251 </p>
1252 </dd>
1253 <dt class="hdlist1">
1254 $projects_list_description_width
1255 </dt>
1256 <dd>
1257 <p>
1258         The width (in characters) of the "Description" column of the projects list.
1259         Longer descriptions will be truncated (trying to cut at word boundary);
1260         the full description is available in the <em>title</em> attribute (usually shown on
1261         mouseover).  The default is 25, which might be too small if you
1262         use long project descriptions.
1263 </p>
1264 </dd>
1265 <dt class="hdlist1">
1266 $default_projects_order
1267 </dt>
1268 <dd>
1269 <p>
1270         Default value of ordering of projects on projects list page, which
1271         means the ordering used if you don&#8217;t explicitly sort projects list
1272         (if there is no "o" CGI query parameter in the URL).  Valid values
1273         are "none" (unsorted), "project" (projects are by project name,
1274         i.e. path to repository relative to <code>$projectroot</code>), "descr"
1275         (project description), "owner", and "age" (by date of most current
1276         commit).
1277 </p>
1278 <div class="paragraph"><p>Default value is "project".  Unknown value means unsorted.</p></div>
1279 </dd>
1280 </dl></div>
1281 </div>
1282 <div class="sect2">
1283 <h3 id="_changing_gitweb_8217_s_behavior">Changing gitweb&#8217;s behavior</h3>
1284 <div class="paragraph"><p>These configuration variables control <em>internal</em> gitweb behavior.</p></div>
1285 <div class="dlist"><dl>
1286 <dt class="hdlist1">
1287 $default_blob_plain_mimetype
1288 </dt>
1289 <dd>
1290 <p>
1291         Default mimetype for the blob_plain (raw) view, if mimetype checking
1292         doesn&#8217;t result in some other type; by default "text/plain".
1293         Gitweb guesses mimetype of a file to display based on extension
1294         of its filename, using <code>$mimetypes_file</code> (if set and file exists)
1295         and <code>/etc/mime.types</code> files (see <strong>mime.types</strong>(5) manpage; only
1296         filename extension rules are supported by gitweb).
1297 </p>
1298 </dd>
1299 <dt class="hdlist1">
1300 $default_text_plain_charset
1301 </dt>
1302 <dd>
1303 <p>
1304         Default charset for text files. If this is not set, the web server
1305         configuration will be used.  Unset by default.
1306 </p>
1307 </dd>
1308 <dt class="hdlist1">
1309 $fallback_encoding
1310 </dt>
1311 <dd>
1312 <p>
1313         Gitweb assumes this charset when a line contains non-UTF-8 characters.
1314         The fallback decoding is used without error checking, so it can be even
1315         "utf-8". The value must be a valid encoding; see the <strong>Encoding::Supported</strong>(3pm)
1316         man page for a list. The default is "latin1", aka. "iso-8859-1".
1317 </p>
1318 </dd>
1319 <dt class="hdlist1">
1320 @diff_opts
1321 </dt>
1322 <dd>
1323 <p>
1324         Rename detection options for git-diff and git-diff-tree. The default is
1325         ('-M'); set it to ('-C') or ('-C', '-C') to also detect copies,
1326         or set it to () i.e. empty list if you don&#8217;t want to have renames
1327         detection.
1328 </p>
1329 <div class="paragraph"><p><strong>Note</strong> that rename and especially copy detection can be quite
1330 CPU-intensive.  Note also that non Git tools can have problems with
1331 patches generated with options mentioned above, especially when they
1332 involve file copies ('-C') or criss-cross renames ('-B').</p></div>
1333 </dd>
1334 </dl></div>
1335 </div>
1336 <div class="sect2">
1337 <h3 id="_some_optional_features_and_policies">Some optional features and policies</h3>
1338 <div class="paragraph"><p>Most of features are configured via <code>%feature</code> hash; however some of extra
1339 gitweb features can be turned on and configured using variables described
1340 below.  This list beside configuration variables that control how gitweb
1341 looks does contain variables configuring administrative side of gitweb
1342 (e.g. cross-site scripting prevention; admittedly this as side effect
1343 affects how "summary" pages look like, or load limiting).</p></div>
1344 <div class="dlist"><dl>
1345 <dt class="hdlist1">
1346 @git_base_url_list
1347 </dt>
1348 <dd>
1349 <p>
1350         List of Git base URLs.  These URLs are used to generate URLs
1351         describing from where to fetch a project, which are shown on
1352         project summary page.  The full fetch URL is "<code>$git_base_url/$project</code>",
1353         for each element of this list. You can set up multiple base URLs
1354         (for example one for <code>git://</code> protocol, and one for <code>http://</code>
1355         protocol).
1356 </p>
1357 <div class="paragraph"><p>Note that per repository configuration can be set in <code>$GIT_DIR/cloneurl</code>
1358 file, or as values of multi-value <code>gitweb.url</code> configuration variable in
1359 project config.  Per-repository configuration takes precedence over value
1360 composed from <code>@git_base_url_list</code> elements and project name.</p></div>
1361 <div class="paragraph"><p>You can setup one single value (single entry/item in this list) at build
1362 time by setting the <code>GITWEB_BASE_URL</code> build-time configuration variable.
1363 By default it is set to (), i.e. an empty list.  This means that gitweb
1364 would not try to create project URL (to fetch) from project name.</p></div>
1365 </dd>
1366 <dt class="hdlist1">
1367 $projects_list_group_categories
1368 </dt>
1369 <dd>
1370 <p>
1371         Whether to enable the grouping of projects by category on the project
1372         list page. The category of a project is determined by the
1373         <code>$GIT_DIR/category</code> file or the <code>gitweb.category</code> variable in each
1374         repository&#8217;s configuration.  Disabled by default (set to 0).
1375 </p>
1376 </dd>
1377 <dt class="hdlist1">
1378 $project_list_default_category
1379 </dt>
1380 <dd>
1381 <p>
1382         Default category for projects for which none is specified.  If this is
1383         set to the empty string, such projects will remain uncategorized and
1384         listed at the top, above categorized projects.  Used only if project
1385         categories are enabled, which means if <code>$projects_list_group_categories</code>
1386         is true.  By default set to "" (empty string).
1387 </p>
1388 </dd>
1389 <dt class="hdlist1">
1390 $prevent_xss
1391 </dt>
1392 <dd>
1393 <p>
1394         If true, some gitweb features are disabled to prevent content in
1395         repositories from launching cross-site scripting (XSS) attacks.  Set this
1396         to true if you don&#8217;t trust the content of your repositories.
1397         False by default (set to 0).
1398 </p>
1399 </dd>
1400 <dt class="hdlist1">
1401 $maxload
1402 </dt>
1403 <dd>
1404 <p>
1405         Used to set the maximum load that we will still respond to gitweb queries.
1406         If the server load exceeds this value then gitweb will return
1407         "503 Service Unavailable" error.  The server load is taken to be 0
1408         if gitweb cannot determine its value.  Currently it works only on Linux,
1409         where it uses <code>/proc/loadavg</code>; the load there is the number of active
1410         tasks on the system&#8201;&#8212;&#8201;processes that are actually running&#8201;&#8212;&#8201;averaged
1411         over the last minute.
1412 </p>
1413 <div class="paragraph"><p>Set <code>$maxload</code> to undefined value (<code>undef</code>) to turn this feature off.
1414 The default value is 300.</p></div>
1415 </dd>
1416 <dt class="hdlist1">
1417 $omit_age_column
1418 </dt>
1419 <dd>
1420 <p>
1421         If true, omit the column with date of the most current commit on the
1422         projects list page. It can save a bit of I/O and a fork per repository.
1423 </p>
1424 </dd>
1425 <dt class="hdlist1">
1426 $omit_owner
1427 </dt>
1428 <dd>
1429 <p>
1430         If true prevents displaying information about repository owner.
1431 </p>
1432 </dd>
1433 <dt class="hdlist1">
1434 $per_request_config
1435 </dt>
1436 <dd>
1437 <p>
1438         If this is set to code reference, it will be run once for each request.
1439         You can set parts of configuration that change per session this way.
1440         For example, one might use the following code in a gitweb configuration
1441         file
1442 </p>
1443 <div class="listingblock">
1444 <div class="content">
1445 <pre><code>our $per_request_config = sub {
1446         $ENV{GL_USER} = $cgi-&gt;remote_user || "gitweb";
1447 };</code></pre>
1448 </div></div>
1449 <div class="paragraph"><p>If <code>$per_request_config</code> is not a code reference, it is interpreted as boolean
1450 value.  If it is true gitweb will process config files once per request,
1451 and if it is false gitweb will process config files only once, each time it
1452 is executed.  True by default (set to 1).</p></div>
1453 <div class="paragraph"><p><strong>NOTE</strong>: <code>$my_url</code>, <code>$my_uri</code>, and <code>$base_url</code> are overwritten with their default
1454 values before every request, so if you want to change them, be sure to set
1455 this variable to true or a code reference effecting the desired changes.</p></div>
1456 <div class="paragraph"><p>This variable matters only when using persistent web environments that
1457 serve multiple requests using single gitweb instance, like mod_perl,
1458 FastCGI or Plackup.</p></div>
1459 </dd>
1460 </dl></div>
1461 </div>
1462 <div class="sect2">
1463 <h3 id="_other_variables">Other variables</h3>
1464 <div class="paragraph"><p>Usually you should not need to change (adjust) any of configuration
1465 variables described below; they should be automatically set by gitweb to
1466 correct value.</p></div>
1467 <div class="dlist"><dl>
1468 <dt class="hdlist1">
1469 $version
1470 </dt>
1471 <dd>
1472 <p>
1473         Gitweb version, set automatically when creating gitweb.cgi from
1474         gitweb.perl. You might want to modify it if you are running modified
1475         gitweb, for example
1476 </p>
1477 <div class="listingblock">
1478 <div class="content">
1479 <pre><code>our $version .= " with caching";</code></pre>
1480 </div></div>
1481 <div class="paragraph"><p>if you run modified version of gitweb with caching support.  This variable
1482 is purely informational, used e.g. in the "generator" meta header in HTML
1483 header.</p></div>
1484 </dd>
1485 <dt class="hdlist1">
1486 $my_url
1487 </dt>
1488 <dt class="hdlist1">
1489 $my_uri
1490 </dt>
1491 <dd>
1492 <p>
1493         Full URL and absolute URL of the gitweb script;
1494         in earlier versions of gitweb you might have need to set those
1495         variables, but now there should be no need to do it.  See
1496         <code>$per_request_config</code> if you need to set them still.
1497 </p>
1498 </dd>
1499 <dt class="hdlist1">
1500 $base_url
1501 </dt>
1502 <dd>
1503 <p>
1504         Base URL for relative URLs in pages generated by gitweb,
1505         (e.g. <code>$logo</code>, <code>$favicon</code>, <code>@stylesheets</code> if they are relative URLs),
1506         needed and used <em>&lt;base href="$base_url"&gt;</em> only for URLs with nonempty
1507         PATH_INFO.  Usually gitweb sets its value correctly,
1508         and there is no need to set this variable, e.g. to $my_uri or "/".
1509         See <code>$per_request_config</code> if you need to override it anyway.
1510 </p>
1511 </dd>
1512 </dl></div>
1513 </div>
1514 </div>
1515 </div>
1516 <div class="sect1">
1517 <h2 id="_configuring_gitweb_features">CONFIGURING GITWEB FEATURES</h2>
1518 <div class="sectionbody">
1519 <div class="paragraph"><p>Many gitweb features can be enabled (or disabled) and configured using the
1520 <code>%feature</code> hash.  Names of gitweb features are keys of this hash.</p></div>
1521 <div class="paragraph"><p>Each <code>%feature</code> hash element is a hash reference and has the following
1522 structure:</p></div>
1523 <div class="listingblock">
1524 <div class="content">
1525 <pre><code>"&lt;feature_name&gt;" =&gt; {
1526         "sub" =&gt; &lt;feature-sub (subroutine)&gt;,
1527         "override" =&gt; &lt;allow-override (boolean)&gt;,
1528         "default" =&gt; [ &lt;options&gt;... ]
1529 },</code></pre>
1530 </div></div>
1531 <div class="paragraph"><p>Some features cannot be overridden per project.  For those
1532 features the structure of appropriate <code>%feature</code> hash element has a simpler
1533 form:</p></div>
1534 <div class="listingblock">
1535 <div class="content">
1536 <pre><code>"&lt;feature_name&gt;" =&gt; {
1537         "override" =&gt; 0,
1538         "default" =&gt; [ &lt;options&gt;... ]
1539 },</code></pre>
1540 </div></div>
1541 <div class="paragraph"><p>As one can see it lacks the 'sub' element.</p></div>
1542 <div class="paragraph"><p>The meaning of each part of feature configuration is described
1543 below:</p></div>
1544 <div class="dlist"><dl>
1545 <dt class="hdlist1">
1546 default
1547 </dt>
1548 <dd>
1549 <p>
1550         List (array reference) of feature parameters (if there are any),
1551         used also to toggle (enable or disable) given feature.
1552 </p>
1553 <div class="paragraph"><p>Note that it is currently <strong>always</strong> an array reference, even if
1554 feature doesn&#8217;t accept any configuration parameters, and 'default'
1555 is used only to turn it on or off.  In such case you turn feature on
1556 by setting this element to <code>[1]</code>, and torn it off by setting it to
1557 <code>[0]</code>.  See also the passage about the "blame" feature in the "Examples"
1558 section.</p></div>
1559 <div class="paragraph"><p>To disable features that accept parameters (are configurable), you
1560 need to set this element to empty list i.e. <code>[]</code>.</p></div>
1561 </dd>
1562 <dt class="hdlist1">
1563 override
1564 </dt>
1565 <dd>
1566 <p>
1567         If this field has a true value then the given feature is
1568         overridable, which means that it can be configured
1569         (or enabled/disabled) on a per-repository basis.
1570 </p>
1571 <div class="paragraph"><p>Usually given "&lt;feature&gt;" is configurable via the <code>gitweb.&lt;feature&gt;</code>
1572 config variable in the per-repository Git configuration file.</p></div>
1573 <div class="paragraph"><p><strong>Note</strong> that no feature is overridable by default.</p></div>
1574 </dd>
1575 <dt class="hdlist1">
1576 sub
1577 </dt>
1578 <dd>
1579 <p>
1580         Internal detail of implementation.  What is important is that
1581         if this field is not present then per-repository override for
1582         given feature is not supported.
1583 </p>
1584 <div class="paragraph"><p>You wouldn&#8217;t need to ever change it in gitweb config file.</p></div>
1585 </dd>
1586 </dl></div>
1587 <div class="sect2">
1588 <h3 id="_features_in_code_feature_code">Features in <code>%feature</code></h3>
1589 <div class="paragraph"><p>The gitweb features that are configurable via <code>%feature</code> hash are listed
1590 below.  This should be a complete list, but ultimately the authoritative
1591 and complete list is in gitweb.cgi source code, with features described
1592 in the comments.</p></div>
1593 <div class="dlist"><dl>
1594 <dt class="hdlist1">
1595 blame
1596 </dt>
1597 <dd>
1598 <p>
1599         Enable the "blame" and "blame_incremental" blob views, showing for
1600         each line the last commit that modified it; see <a href="git-blame.html">git-blame(1)</a>.
1601         This can be very CPU-intensive and is therefore disabled by default.
1602 </p>
1603 <div class="paragraph"><p>This feature can be configured on a per-repository basis via
1604 repository&#8217;s <code>gitweb.blame</code> configuration variable (boolean).</p></div>
1605 </dd>
1606 <dt class="hdlist1">
1607 snapshot
1608 </dt>
1609 <dd>
1610 <p>
1611         Enable and configure the "snapshot" action, which allows user to
1612         download a compressed archive of any tree or commit, as produced
1613         by <a href="git-archive.html">git-archive(1)</a> and possibly additionally compressed.
1614         This can potentially generate high traffic if you have large project.
1615 </p>
1616 <div class="paragraph"><p>The value of 'default' is a list of names of snapshot formats,
1617 defined in <code>%known_snapshot_formats</code> hash, that you wish to offer.
1618 Supported formats include "tgz", "tbz2", "txz" (gzip/bzip2/xz
1619 compressed tar archive) and "zip"; please consult gitweb sources for
1620 a definitive list.  By default only "tgz" is offered.</p></div>
1621 <div class="paragraph"><p>This feature can be configured on a per-repository basis via
1622 repository&#8217;s <code>gitweb.snapshot</code> configuration variable, which contains
1623 a comma separated list of formats or "none" to disable snapshots.
1624 Unknown values are ignored.</p></div>
1625 </dd>
1626 <dt class="hdlist1">
1627 grep
1628 </dt>
1629 <dd>
1630 <p>
1631         Enable grep search, which lists the files in currently selected
1632         tree (directory) containing the given string; see <a href="git-grep.html">git-grep(1)</a>.
1633         This can be potentially CPU-intensive, of course.  Enabled by default.
1634 </p>
1635 <div class="paragraph"><p>This feature can be configured on a per-repository basis via
1636 repository&#8217;s <code>gitweb.grep</code> configuration variable (boolean).</p></div>
1637 </dd>
1638 <dt class="hdlist1">
1639 pickaxe
1640 </dt>
1641 <dd>
1642 <p>
1643         Enable the so called pickaxe search, which will list the commits
1644         that introduced or removed a given string in a file.  This can be
1645         practical and quite faster alternative to "blame" action, but it is
1646         still potentially CPU-intensive.  Enabled by default.
1647 </p>
1648 <div class="paragraph"><p>The pickaxe search is described in <a href="git-log.html">git-log(1)</a> (the
1649 description of <code>-S&lt;string&gt;</code> option, which refers to pickaxe entry in
1650 <a href="gitdiffcore.html">gitdiffcore(7)</a> for more details).</p></div>
1651 <div class="paragraph"><p>This feature can be configured on a per-repository basis by setting
1652 repository&#8217;s <code>gitweb.pickaxe</code> configuration variable (boolean).</p></div>
1653 </dd>
1654 <dt class="hdlist1">
1655 show-sizes
1656 </dt>
1657 <dd>
1658 <p>
1659         Enable showing size of blobs (ordinary files) in a "tree" view, in a
1660         separate column, similar to what <code>ls -l</code> does; see description of
1661         <code>-l</code> option in <a href="git-ls-tree.html">git-ls-tree(1)</a> manpage.  This costs a bit of
1662         I/O.  Enabled by default.
1663 </p>
1664 <div class="paragraph"><p>This feature can be configured on a per-repository basis via
1665 repository&#8217;s <code>gitweb.showSizes</code> configuration variable (boolean).</p></div>
1666 </dd>
1667 <dt class="hdlist1">
1668 patches
1669 </dt>
1670 <dd>
1671 <p>
1672         Enable and configure "patches" view, which displays list of commits in email
1673         (plain text) output format; see also <a href="git-format-patch.html">git-format-patch(1)</a>.
1674         The value is the maximum number of patches in a patchset generated
1675         in "patches" view.  Set the <em>default</em> field to a list containing single
1676         item of or to an empty list to disable patch view, or to a list
1677         containing a single negative number to remove any limit.
1678         Default value is 16.
1679 </p>
1680 <div class="paragraph"><p>This feature can be configured on a per-repository basis via
1681 repository&#8217;s <code>gitweb.patches</code> configuration variable (integer).</p></div>
1682 </dd>
1683 <dt class="hdlist1">
1684 avatar
1685 </dt>
1686 <dd>
1687 <p>
1688         Avatar support.  When this feature is enabled, views such as
1689         "shortlog" or "commit" will display an avatar associated with
1690         the email of each committer and author.
1691 </p>
1692 <div class="paragraph"><p>Currently available providers are <strong>"gravatar"</strong> and <strong>"picon"</strong>.
1693 Only one provider at a time can be selected (<em>default</em> is one element list).
1694 If an unknown provider is specified, the feature is disabled.
1695 <strong>Note</strong> that some providers might require extra Perl packages to be
1696 installed; see <code>gitweb/INSTALL</code> for more details.</p></div>
1697 <div class="paragraph"><p>This feature can be configured on a per-repository basis via
1698 repository&#8217;s <code>gitweb.avatar</code> configuration variable.</p></div>
1699 <div class="paragraph"><p>See also <code>%avatar_size</code> with pixel sizes for icons and avatars
1700 ("default" is used for one-line like "log" and "shortlog", "double"
1701 is used for two-line like "commit", "commitdiff" or "tag").  If the
1702 default font sizes or lineheights are changed (e.g. via adding extra
1703 CSS stylesheet in <code>@stylesheets</code>), it may be appropriate to change
1704 these values.</p></div>
1705 </dd>
1706 <dt class="hdlist1">
1707 email-privacy
1708 </dt>
1709 <dd>
1710 <p>
1711         Redact e-mail addresses from the generated HTML, etc. content.
1712         This obscures e-mail addresses retrieved from the author/committer
1713         and comment sections of the Git log.
1714         It is meant to hinder web crawlers that harvest and abuse addresses.
1715         Such crawlers may not respect robots.txt.
1716         Note that users and user tools also see the addresses as redacted.
1717         If Gitweb is not the final step in a workflow then subsequent steps
1718         may misbehave because of the redacted information they receive.
1719         Disabled by default.
1720 </p>
1721 </dd>
1722 <dt class="hdlist1">
1723 highlight
1724 </dt>
1725 <dd>
1726 <p>
1727         Server-side syntax highlight support in "blob" view.  It requires
1728         <code>$highlight_bin</code> program to be available (see the description of
1729         this variable in the "Configuration variables" section above),
1730         and therefore is disabled by default.
1731 </p>
1732 <div class="paragraph"><p>This feature can be configured on a per-repository basis via
1733 repository&#8217;s <code>gitweb.highlight</code> configuration variable (boolean).</p></div>
1734 </dd>
1735 <dt class="hdlist1">
1736 remote_heads
1737 </dt>
1738 <dd>
1739 <p>
1740         Enable displaying remote heads (remote-tracking branches) in the "heads"
1741         list.  In most cases the list of remote-tracking branches is an
1742         unnecessary internal private detail, and this feature is therefore
1743         disabled by default.  <a href="git-instaweb.html">git-instaweb(1)</a>, which is usually used
1744         to browse local repositories, enables and uses this feature.
1745 </p>
1746 <div class="paragraph"><p>This feature can be configured on a per-repository basis via
1747 repository&#8217;s <code>gitweb.remote_heads</code> configuration variable (boolean).</p></div>
1748 </dd>
1749 </dl></div>
1750 <div class="paragraph"><p>The remaining features cannot be overridden on a per project basis.</p></div>
1751 <div class="dlist"><dl>
1752 <dt class="hdlist1">
1753 search
1754 </dt>
1755 <dd>
1756 <p>
1757         Enable text search, which will list the commits which match author,
1758         committer or commit text to a given string; see the description of
1759         <code>--author</code>, <code>--committer</code> and <code>--grep</code> options in <a href="git-log.html">git-log(1)</a>
1760         manpage.  Enabled by default.
1761 </p>
1762 <div class="paragraph"><p>Project specific override is not supported.</p></div>
1763 </dd>
1764 <dt class="hdlist1">
1765 forks
1766 </dt>
1767 <dd>
1768 <p>
1769         If this feature is enabled, gitweb considers projects in
1770         subdirectories of project root (basename) to be forks of existing
1771         projects.  For each project <code>$projname.git</code>, projects in the
1772         <code>$projname/</code> directory and its subdirectories will not be
1773         shown in the main projects list.  Instead, a '+' mark is shown
1774         next to <code>$projname</code>, which links to a "forks" view that lists all
1775         the forks (all projects in <code>$projname/</code> subdirectory).  Additionally
1776         a "forks" view for a project is linked from project summary page.
1777 </p>
1778 <div class="paragraph"><p>If the project list is taken from a file (<code>$projects_list</code> points to a
1779 file), forks are only recognized if they are listed after the main project
1780 in that file.</p></div>
1781 <div class="paragraph"><p>Project specific override is not supported.</p></div>
1782 </dd>
1783 <dt class="hdlist1">
1784 actions
1785 </dt>
1786 <dd>
1787 <p>
1788         Insert custom links to the action bar of all project pages.  This
1789         allows you to link to third-party scripts integrating into gitweb.
1790 </p>
1791 <div class="paragraph"><p>The "default" value consists of a list of triplets in the form
1792 &#8216;("&lt;label&gt;", "&lt;link&gt;", "&lt;position&gt;")` where "position" is the label
1793 after which to insert the link, "link" is a format string where <code>%n</code>
1794 expands to the project name, <code>%f</code> to the project path within the
1795 filesystem (i.e. "$projectroot/$project"), <code>%h</code> to the current hash
1796 ('h&#8217; gitweb parameter) and &#8216;%b` to the current hash base
1797 ('hb&#8217; gitweb parameter); &#8216;%%` expands to '%&#8217;.</p></div>
1798 <div class="paragraph"><p>For example, at the time this page was written, the <a href="https://repo.or.cz">https://repo.or.cz</a>
1799 Git hosting site set it to the following to enable graphical log
1800 (using the third party tool <strong>git-browser</strong>):</p></div>
1801 <div class="listingblock">
1802 <div class="content">
1803 <pre><code>$feature{'actions'}{'default'} =
1804         [ ('graphiclog', '/git-browser/by-commit.html?r=%n', 'summary')];</code></pre>
1805 </div></div>
1806 <div class="paragraph"><p>This adds a link titled "graphiclog" after the "summary" link, leading to
1807 <code>git-browser</code> script, passing <code>r=&lt;project&gt;</code> as a query parameter.</p></div>
1808 <div class="paragraph"><p>Project specific override is not supported.</p></div>
1809 </dd>
1810 <dt class="hdlist1">
1811 timed
1812 </dt>
1813 <dd>
1814 <p>
1815         Enable displaying how much time and how many Git commands it took to
1816         generate and display each page in the page footer (at the bottom of
1817         page).  For example the footer might contain: "This page took 6.53325
1818         seconds and 13 Git commands to generate."  Disabled by default.
1819 </p>
1820 <div class="paragraph"><p>Project specific override is not supported.</p></div>
1821 </dd>
1822 <dt class="hdlist1">
1823 javascript-timezone
1824 </dt>
1825 <dd>
1826 <p>
1827         Enable and configure the ability to change a common time zone for dates
1828         in gitweb output via JavaScript.  Dates in gitweb output include
1829         authordate and committerdate in "commit", "commitdiff" and "log"
1830         views, and taggerdate in "tag" view.  Enabled by default.
1831 </p>
1832 <div class="paragraph"><p>The value is a list of three values: a default time zone (for if the client
1833 hasn&#8217;t selected some other time zone and saved it in a cookie), a name of cookie
1834 where to store selected time zone, and a CSS class used to mark up
1835 dates for manipulation.  If you want to turn this feature off, set "default"
1836 to empty list: <code>[]</code>.</p></div>
1837 <div class="paragraph"><p>Typical gitweb config files will only change starting (default) time zone,
1838 and leave other elements at their default values:</p></div>
1839 <div class="listingblock">
1840 <div class="content">
1841 <pre><code>$feature{'javascript-timezone'}{'default'}[0] = "utc";</code></pre>
1842 </div></div>
1843 <div class="paragraph"><p>The example configuration presented here is guaranteed to be backwards
1844 and forward compatible.</p></div>
1845 <div class="paragraph"><p>Time zone values can be "local" (for local time zone that browser uses), "utc"
1846 (what gitweb uses when JavaScript or this feature is disabled), or numerical
1847 time zones in the form of "+/-HHMM", such as "+0200".</p></div>
1848 <div class="paragraph"><p>Project specific override is not supported.</p></div>
1849 </dd>
1850 <dt class="hdlist1">
1851 extra-branch-refs
1852 </dt>
1853 <dd>
1854 <p>
1855         List of additional directories under "refs" which are going to
1856         be used as branch refs. For example if you have a gerrit setup
1857         where all branches under refs/heads/ are official,
1858         push-after-review ones and branches under refs/sandbox/,
1859         refs/wip and refs/other are user ones where permissions are
1860         much wider, then you might want to set this variable as
1861         follows:
1862 </p>
1863 <div class="listingblock">
1864 <div class="content">
1865 <pre><code>$feature{'extra-branch-refs'}{'default'} =
1866         ['sandbox', 'wip', 'other'];</code></pre>
1867 </div></div>
1868 <div class="paragraph"><p>This feature can be configured on per-repository basis after setting
1869 $feature{<em>extra-branch-refs</em>}{<em>override</em>} to true, via repository&#8217;s
1870 <code>gitweb.extraBranchRefs</code> configuration variable, which contains a
1871 space separated list of refs. An example:</p></div>
1872 <div class="listingblock">
1873 <div class="content">
1874 <pre><code>[gitweb]
1875         extraBranchRefs = sandbox wip other</code></pre>
1876 </div></div>
1877 <div class="paragraph"><p>The gitweb.extraBranchRefs is actually a multi-valued configuration
1878 variable, so following example is also correct and the result is the
1879 same as of the snippet above:</p></div>
1880 <div class="listingblock">
1881 <div class="content">
1882 <pre><code>[gitweb]
1883         extraBranchRefs = sandbox
1884         extraBranchRefs = wip other</code></pre>
1885 </div></div>
1886 <div class="paragraph"><p>It is an error to specify a ref that does not pass "git check-ref-format"
1887 scrutiny. Duplicated values are filtered.</p></div>
1888 </dd>
1889 </dl></div>
1890 </div>
1891 </div>
1892 </div>
1893 <div class="sect1">
1894 <h2 id="_examples">EXAMPLES</h2>
1895 <div class="sectionbody">
1896 <div class="paragraph"><p>To enable blame, pickaxe search, and snapshot support (allowing "tar.gz" and
1897 "zip" snapshots), while allowing individual projects to turn them off, put
1898 the following in your GITWEB_CONFIG file:</p></div>
1899 <div class="listingblock">
1900 <div class="content">
1901 <pre><code>$feature{'blame'}{'default'} = [1];
1902 $feature{'blame'}{'override'} = 1;
1903
1904 $feature{'pickaxe'}{'default'} = [1];
1905 $feature{'pickaxe'}{'override'} = 1;
1906
1907 $feature{'snapshot'}{'default'} = ['zip', 'tgz'];
1908 $feature{'snapshot'}{'override'} = 1;</code></pre>
1909 </div></div>
1910 <div class="paragraph"><p>If you allow overriding for the snapshot feature, you can specify which
1911 snapshot formats are globally disabled. You can also add any command-line
1912 options you want (such as setting the compression level). For instance, you
1913 can disable Zip compressed snapshots and set <strong>gzip</strong>(1) to run at level 6 by
1914 adding the following lines to your gitweb configuration file:</p></div>
1915 <div class="literalblock">
1916 <div class="content">
1917 <pre><code>$known_snapshot_formats{'zip'}{'disabled'} = 1;
1918 $known_snapshot_formats{'tgz'}{'compressor'} = ['gzip','-6'];</code></pre>
1919 </div></div>
1920 </div>
1921 </div>
1922 <div class="sect1">
1923 <h2 id="_bugs">BUGS</h2>
1924 <div class="sectionbody">
1925 <div class="paragraph"><p>Debugging would be easier if the fallback configuration file
1926 (<code>/etc/gitweb.conf</code>) and environment variable to override its location
1927 (<em>GITWEB_CONFIG_SYSTEM</em>) had names reflecting their "fallback" role.
1928 The current names are kept to avoid breaking working setups.</p></div>
1929 </div>
1930 </div>
1931 <div class="sect1">
1932 <h2 id="_environment">ENVIRONMENT</h2>
1933 <div class="sectionbody">
1934 <div class="paragraph"><p>The location of per-instance and system-wide configuration files can be
1935 overridden using the following environment variables:</p></div>
1936 <div class="dlist"><dl>
1937 <dt class="hdlist1">
1938 GITWEB_CONFIG
1939 </dt>
1940 <dd>
1941 <p>
1942         Sets location of per-instance configuration file.
1943 </p>
1944 </dd>
1945 <dt class="hdlist1">
1946 GITWEB_CONFIG_SYSTEM
1947 </dt>
1948 <dd>
1949 <p>
1950         Sets location of fallback system-wide configuration file.
1951         This file is read only if per-instance one does not exist.
1952 </p>
1953 </dd>
1954 <dt class="hdlist1">
1955 GITWEB_CONFIG_COMMON
1956 </dt>
1957 <dd>
1958 <p>
1959         Sets location of common system-wide configuration file.
1960 </p>
1961 </dd>
1962 </dl></div>
1963 </div>
1964 </div>
1965 <div class="sect1">
1966 <h2 id="_files">FILES</h2>
1967 <div class="sectionbody">
1968 <div class="dlist"><dl>
1969 <dt class="hdlist1">
1970 gitweb_config.perl
1971 </dt>
1972 <dd>
1973 <p>
1974         This is default name of per-instance configuration file.  The
1975         format of this file is described above.
1976 </p>
1977 </dd>
1978 <dt class="hdlist1">
1979 /etc/gitweb.conf
1980 </dt>
1981 <dd>
1982 <p>
1983         This is default name of fallback system-wide configuration
1984         file.  This file is used only if per-instance configuration
1985         variable is not found.
1986 </p>
1987 </dd>
1988 <dt class="hdlist1">
1989 /etc/gitweb-common.conf
1990 </dt>
1991 <dd>
1992 <p>
1993         This is default name of common system-wide configuration
1994         file.
1995 </p>
1996 </dd>
1997 </dl></div>
1998 </div>
1999 </div>
2000 <div class="sect1">
2001 <h2 id="_see_also">SEE ALSO</h2>
2002 <div class="sectionbody">
2003 <div class="paragraph"><p><a href="gitweb.html">gitweb(1)</a>, <a href="git-instaweb.html">git-instaweb(1)</a></p></div>
2004 <div class="paragraph"><p><em>gitweb/README</em>, <em>gitweb/INSTALL</em></p></div>
2005 </div>
2006 </div>
2007 <div class="sect1">
2008 <h2 id="_git">GIT</h2>
2009 <div class="sectionbody">
2010 <div class="paragraph"><p>Part of the <a href="git.html">git(1)</a> suite</p></div>
2011 </div>
2012 </div>
2013 </div>
2014 <div id="footnotes"><hr /></div>
2015 <div id="footer">
2016 <div id="footer-text">
2017 Last updated
2018  2023-12-18 14:49:41 PST
2019 </div>
2020 </div>
2021 </body>
2022 </html>