cgitrc.5.txt

   1 :man source:   cgit
   2 :man manual:   cgit
   3
   4 CGITRC(5)
   5 ========
   6
   7
   8 NAME
   9 ----
  10 cgitrc - runtime configuration for cgit
  11
  12
  13 SYNOPSIS
  14 --------
  15 Cgitrc contains all runtime settings for cgit, including the list of git
  16 repositories, formatted as a line-separated list of NAME=VALUE pairs. Blank
  17 lines, and lines starting with '#', are ignored.
  18
  19
  20 LOCATION
  21 --------
  22 The default location of cgitrc, defined at compile time, is /etc/cgitrc. At
  23 runtime, cgit will consult the environment variable CGIT_CONFIG and, if
  24 defined, use its value instead.
  25
  26
  27 GLOBAL SETTINGS
  28 ---------------
  29 about-filter::
  30         Specifies a command which will be invoked to format the content of
  31         about pages (both top-level and for each repository). The command will
  32         get the content of the about-file on its STDIN, the name of the file
  33         as the first argument, and the STDOUT from the command will be
  34         included verbatim on the about page. Default value: none. See
  35         also: "FILTER API".
  36
  37 agefile::
  38         Specifies a path, relative to each repository path, which can be used
  39         to specify the date and time of the youngest commit in the repository.
  40         The first line in the file is used as input to the "parse_date"
  41         function in libgit. Recommended timestamp-format is "yyyy-mm-dd
  42         hh:mm:ss". You may want to generate this file from a post-receive
  43         hook. Default value: "info/web/last-modified".
  44
  45 auth-filter::
  46         Specifies a command that will be invoked for authenticating repository
  47         access. Receives quite a few arguments, and data on both stdin and
  48         stdout for authentication processing. Details follow later in this
  49         document. If no auth-filter is specified, no authentication is
  50         performed. Default value: none. See also: "FILTER API".
  51
  52 branch-sort::
  53         Flag which, when set to "age", enables date ordering in the branch ref
  54         list, and when set to "name" enables ordering by branch name. Default
  55         value: "name".
  56
  57 cache-root::
  58         Path used to store the cgit cache entries. Default value:
  59         "/var/cache/cgit". See also: "MACRO EXPANSION".
  60
  61 cache-static-ttl::
  62         Number which specifies the time-to-live, in minutes, for the cached
  63         version of repository pages accessed with a fixed SHA1. Negative
  64         values have infinite ttl, zero means that the cache is disabled for
  65         this type of pages. Default value: -1".
  66
  67 cache-dynamic-ttl::
  68         Number which specifies the time-to-live, in minutes, for the cached
  69         version of repository pages accessed without a fixed SHA1. Negative
  70         values have infinite ttl, zero means that the cache is disabled for this
  71         type of pages. Default value: "5".
  72
  73 cache-repo-ttl::
  74         Number which specifies the time-to-live, in minutes, for the cached
  75         version of the repository summary page. Negative values have infinite
  76         ttl, zero means that the cache is disabled for this type of pages.
  77         Default value: "5".
  78
  79 cache-root-ttl::
  80         Number which specifies the time-to-live, in minutes, for the cached
  81         version of the repository index page. Negative values have infinite
  82         ttl, zero means that the cache is disabled for this type of pages.
  83         Default value: "5".
  84
  85 cache-scanrc-ttl::
  86         Number which specifies the time-to-live, in minutes, for the result
  87         of scanning a path for git repositories. Negative values have infinite
  88         ttl, zero means that the cache is disable for this type of pages.
  89         Default value: "15".
  90
  91 cache-about-ttl::
  92         Number which specifies the time-to-live, in minutes, for the cached
  93         version of the repository about page. Negative values have infinite
  94         ttl, zero means that the cache is disable for this type of pages.
  95         Default value: "15".
  96
  97 cache-snapshot-ttl::
  98         Number which specifies the time-to-live, in minutes, for the cached
  99         version of snapshots. Negative values have infinite ttl, zero means
 100         that the cache is disable for this type of pages. Default value: "5".
 101
 102 cache-size::
 103         The maximum number of entries in the cgit cache. Default value: "0"
 104         (i.e. caching is disabled).
 105
 106 case-sensitive-sort::
 107         Sort items in the repo list case sensitively. Default value: "1".
 108         See also: repository-sort, section-sort.
 109
 110 clone-prefix::
 111         Space-separated list of common prefixes which, when combined with a
 112         repository url, generates valid clone urls for the repository. This
 113         setting is only used if `repo.clone-url` is unspecified. Default value:
 114         none.
 115
 116 clone-url::
 117         Space-separated list of clone-url templates. This setting is only
 118         used if `repo.clone-url` is unspecified. Default value: none. See
 119         also: "MACRO EXPANSION", "FILTER API".
 120
 121 commit-filter::
 122         Specifies a command which will be invoked to format commit messages.
 123         The command will get the message on its STDIN, and the STDOUT from the
 124         command will be included verbatim as the commit message, i.e. this can
 125         be used to implement bugtracker integration. Default value: none.
 126         See also: "FILTER API".
 127
 128 commit-sort::
 129         Flag which, when set to "date", enables strict date ordering in the
 130         commit log, and when set to "topo" enables strict topological
 131         ordering. If unset, the default ordering of "git log" is used. Default
 132         value: unset.
 133
 134 css::
 135         Url which specifies the css document to include in all cgit pages.
 136         Default value: "/cgit.css".
 137
 138 email-filter::
 139         Specifies a command which will be invoked to format names and email
 140         address of committers, authors, and taggers, as represented in various
 141         places throughout the cgit interface. This command will receive an
 142         email address and an origin page string as its command line arguments,
 143         and the text to format on STDIN. It is to write the formatted text back
 144         out onto STDOUT. Default value: none. See also: "FILTER API".
 145
 146 embedded::
 147         Flag which, when set to "1", will make cgit generate a html fragment
 148         suitable for embedding in other html pages. Default value: none. See
 149         also: "noheader".
 150
 151 enable-commit-graph::
 152         Flag which, when set to "1", will make cgit print an ASCII-art commit
 153         history graph to the left of the commit messages in the repository
 154         log page. Default value: "0".
 155
 156 enable-filter-overrides::
 157         Flag which, when set to "1", allows all filter settings to be
 158         overridden in repository-specific cgitrc files. Default value: none.
 159
 160 enable-http-clone::
 161         If set to "1", cgit will act as an dumb HTTP endpoint for git clones.
 162         You can add "http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL" to clone-url
 163         to expose this feature. If you use an alternate way of serving git
 164         repositories, you may wish to disable this. Default value: "1".
 165
 166 enable-index-links::
 167         Flag which, when set to "1", will make cgit generate extra links for
 168         each repo in the repository index (specifically, to the "summary",
 169         "commit" and "tree" pages). Default value: "0".
 170
 171 enable-index-owner::
 172         Flag which, when set to "1", will make cgit display the owner of
 173         each repo in the repository index. Default value: "1".
 174
 175 enable-log-filecount::
 176         Flag which, when set to "1", will make cgit print the number of
 177         modified files for each commit on the repository log page. Default
 178         value: "0".
 179
 180 enable-log-linecount::
 181         Flag which, when set to "1", will make cgit print the number of added
 182         and removed lines for each commit on the repository log page. Default
 183         value: "0".
 184
 185 enable-remote-branches::
 186         Flag which, when set to "1", will make cgit display remote branches
 187         in the summary and refs views. Default value: "0". See also:
 188         "repo.enable-remote-branches".
 189
 190 enable-subject-links::
 191         Flag which, when set to "1", will make cgit use the subject of the
 192         parent commit as link text when generating links to parent commits
 193         in commit view. Default value: "0". See also:
 194         "repo.enable-subject-links".
 195
 196 enable-tree-linenumbers::
 197         Flag which, when set to "1", will make cgit generate linenumber links
 198         for plaintext blobs printed in the tree view. Default value: "1".
 199
 200 enable-git-config::
 201         Flag which, when set to "1", will allow cgit to use git config to set
 202         any repo specific settings. This option is used in conjunction with
 203         "scan-path", and must be defined prior, to augment repo-specific
 204         settings. The keys gitweb.owner, gitweb.category, and gitweb.description
 205         will map to the cgit keys repo.owner, repo.section, and repo.desc,
 206         respectively. All git config keys that begin with "cgit." will be mapped
 207         to the corresponding "repo." key in cgit. Default value: "0". See also:
 208         scan-path, section-from-path.
 209
 210 favicon::
 211         Url used as link to a shortcut icon for cgit. It is suggested to use
 212         the value "/favicon.ico" since certain browsers will ignore other
 213         values. Default value: "/favicon.ico".
 214
 215 footer::
 216         The content of the file specified with this option will be included
 217         verbatim at the bottom of all pages (i.e. it replaces the standard
 218         "generated by..." message. Default value: none.
 219
 220 head-include::
 221         The content of the file specified with this option will be included
 222         verbatim in the html HEAD section on all pages. Default value: none.
 223
 224 header::
 225         The content of the file specified with this option will be included
 226         verbatim at the top of all pages. Default value: none.
 227
 228 include::
 229         Name of a configfile to include before the rest of the current config-
 230         file is parsed. Default value: none. See also: "MACRO EXPANSION".
 231
 232 index-header::
 233         The content of the file specified with this option will be included
 234         verbatim above the repository index. This setting is deprecated, and
 235         will not be supported by cgit-1.0 (use root-readme instead). Default
 236         value: none.
 237
 238 index-info::
 239         The content of the file specified with this option will be included
 240         verbatim below the heading on the repository index page. This setting
 241         is deprecated, and will not be supported by cgit-1.0 (use root-desc
 242         instead). Default value: none.
 243
 244 local-time::
 245         Flag which, if set to "1", makes cgit print commit and tag times in the
 246         servers timezone. Default value: "0".
 247
 248 logo::
 249         Url which specifies the source of an image which will be used as a logo
 250         on all cgit pages. Default value: "/cgit.png".
 251
 252 logo-link::
 253         Url loaded when clicking on the cgit logo image. If unspecified the
 254         calculated url of the repository index page will be used. Default
 255         value: none.
 256
 257 max-atom-items::
 258         Specifies the number of items to display in atom feeds view. Default
 259         value: "10".
 260
 261 max-commit-count::
 262         Specifies the number of entries to list per page in "log" view. Default
 263         value: "50".
 264
 265 max-message-length::
 266         Specifies the maximum number of commit message characters to display in
 267         "log" view. Default value: "80".
 268
 269 max-repo-count::
 270         Specifies the number of entries to list per page on the repository
 271         index page. Default value: "50".
 272
 273 max-repodesc-length::
 274         Specifies the maximum number of repo description characters to display
 275         on the repository index page. Default value: "80".
 276
 277 max-blob-size::
 278         Specifies the maximum size of a blob to display HTML for in KBytes.
 279         Default value: "0" (limit disabled).
 280
 281 max-stats::
 282         Set the default maximum statistics period. Valid values are "week",
 283         "month", "quarter" and "year". If unspecified, statistics are
 284         disabled. Default value: none. See also: "repo.max-stats".
 285
 286 mimetype.<ext>::
 287         Set the mimetype for the specified filename extension. This is used
 288         by the `plain` command when returning blob content.
 289
 290 mimetype-file::
 291         Specifies the file to use for automatic mimetype lookup. If specified
 292         then this field is used as a fallback when no "mimetype.<ext>" match is
 293         found. If unspecified then no such lookup is performed. The typical file
 294         to use on a Linux system is /etc/mime.types. The format of the file must
 295         comply to:
 296         - a comment line is an empty line or a line starting with a hash (#),
 297           optionally preceded by whitespace
 298         - a non-comment line starts with the mimetype (like image/png), followed
 299           by one or more file extensions (like jpg), all separated by whitespace
 300         Default value: none. See also: "mimetype.<ext>".
 301
 302 module-link::
 303         Text which will be used as the formatstring for a hyperlink when a
 304         submodule is printed in a directory listing. The arguments for the
 305         formatstring are the path and SHA1 of the submodule commit. Default
 306         value: none.
 307
 308 nocache::
 309         If set to the value "1" caching will be disabled. This settings is
 310         deprecated, and will not be honored starting with cgit-1.0. Default
 311         value: "0".
 312
 313 noplainemail::
 314         If set to "1" showing full author email addresses will be disabled.
 315         Default value: "0".
 316
 317 noheader::
 318         Flag which, when set to "1", will make cgit omit the standard header
 319         on all pages. Default value: none. See also: "embedded".
 320
 321 project-list::
 322         A list of subdirectories inside of scan-path, relative to it, that
 323         should loaded as git repositories. This must be defined prior to
 324         scan-path. Default value: none. See also: scan-path, "MACRO
 325         EXPANSION".
 326
 327 readme::
 328         Text which will be used as default value for "repo.readme". Multiple
 329         config keys may be specified, and cgit will use the first found file
 330         in this list. This is useful in conjunction with scan-path. Default
 331         value: none. See also: scan-path, repo.readme.
 332
 333 remove-suffix::
 334         If set to "1" and scan-path is enabled, if any repositories are found
 335         with a suffix of ".git", this suffix will be removed for the url and
 336         name. This must be defined prior to scan-path. Default value: "0".
 337         See also: scan-path.
 338
 339 renamelimit::
 340         Maximum number of files to consider when detecting renames. The value
 341          "-1" uses the compiletime value in git (for further info, look at
 342           `man git-diff`). Default value: "-1".
 343
 344 repo.group::
 345         Legacy alias for "section". This option is deprecated and will not be
 346         supported in cgit-1.0.
 347
 348 repository-sort::
 349         The way in which repositories in each section are sorted. Valid values
 350         are "name" for sorting by the repo name or "age" for sorting by the
 351         most recently updated repository. Default value: "name". See also:
 352         section, case-sensitive-sort, section-sort.
 353
 354 robots::
 355         Text used as content for the "robots" meta-tag. Default value:
 356         "index, nofollow".
 357
 358 root-desc::
 359         Text printed below the heading on the repository index page. Default
 360         value: "a fast webinterface for the git dscm".
 361
 362 root-readme::
 363         The content of the file specified with this option will be included
 364         verbatim below the "about" link on the repository index page. Default
 365         value: none.
 366
 367 root-title::
 368         Text printed as heading on the repository index page. Default value:
 369         "Git Repository Browser".
 370
 371 scan-hidden-path::
 372         If set to "1" and scan-path is enabled, scan-path will recurse into
 373         directories whose name starts with a period ('.'). Otherwise,
 374         scan-path will stay away from such directories (considered as
 375         "hidden"). Note that this does not apply to the ".git" directory in
 376         non-bare repos. This must be defined prior to scan-path.
 377         Default value: 0. See also: scan-path.
 378
 379 scan-path::
 380         A path which will be scanned for repositories. If caching is enabled,
 381         the result will be cached as a cgitrc include-file in the cache
 382         directory. If project-list has been defined prior to scan-path,
 383         scan-path loads only the directories listed in the file pointed to by
 384         project-list. Be advised that only the global settings taken
 385         before the scan-path directive will be applied to each repository.
 386         Default value: none. See also: cache-scanrc-ttl, project-list,
 387         "MACRO EXPANSION".
 388
 389 section::
 390         The name of the current repository section - all repositories defined
 391         after this option will inherit the current section name. Default value:
 392         none.
 393
 394 section-sort::
 395         Flag which, when set to "1", will sort the sections on the repository
 396         listing by name. Set this flag to "0" if the order in the cgitrc file should
 397         be preserved. Default value: "1". See also: section,
 398         case-sensitive-sort, repository-sort.
 399
 400 section-from-path::
 401         A number which, if defined prior to scan-path, specifies how many
 402         path elements from each repo path to use as a default section name.
 403         If negative, cgit will discard the specified number of path elements
 404         above the repo directory. Default value: "0".
 405
 406 side-by-side-diffs::
 407         If set to "1" shows side-by-side diffs instead of unidiffs per
 408         default. Default value: "0".
 409
 410 snapshots::
 411         Text which specifies the default set of snapshot formats that cgit
 412         generates links for. The value is a space-separated list of zero or
 413         more of the values "tar", "tar.gz", "tar.bz2", "tar.xz" and "zip".
 414         Default value: none.
 415
 416 source-filter::
 417         Specifies a command which will be invoked to format plaintext blobs
 418         in the tree view. The command will get the blob content on its STDIN
 419         and the name of the blob as its only command line argument. The STDOUT
 420         from the command will be included verbatim as the blob contents, i.e.
 421         this can be used to implement e.g. syntax highlighting. Default value:
 422         none. See also: "FILTER API".
 423
 424 summary-branches::
 425         Specifies the number of branches to display in the repository "summary"
 426         view. Default value: "10".
 427
 428 summary-log::
 429         Specifies the number of log entries to display in the repository
 430         "summary" view. Default value: "10".
 431
 432 summary-tags::
 433         Specifies the number of tags to display in the repository "summary"
 434         view. Default value: "10".
 435
 436 strict-export::
 437         Filename which, if specified, needs to be present within the repository
 438         for cgit to allow access to that repository. This can be used to emulate
 439         gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's
 440         repositories to match those exported by git-daemon. This option must
 441         be defined prior to scan-path.
 442
 443 virtual-root::
 444         Url which, if specified, will be used as root for all cgit links. It
 445         will also cause cgit to generate 'virtual urls', i.e. urls like
 446         '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
 447         value: none.
 448         NOTE: cgit has recently learned how to use PATH_INFO to achieve the
 449         same kind of virtual urls, so this option will probably be deprecated.
 450
 451
 452 REPOSITORY SETTINGS
 453 -------------------
 454 repo.about-filter::
 455         Override the default about-filter. Default value: none. See also:
 456         "enable-filter-overrides". See also: "FILTER API".
 457
 458 repo.branch-sort::
 459         Flag which, when set to "age", enables date ordering in the branch ref
 460         list, and when set to "name" enables ordering by branch name. Default
 461         value: "name".
 462
 463 repo.clone-url::
 464         A list of space-separated urls which can be used to clone this repo.
 465         Default value: none. See also: "MACRO EXPANSION".
 466
 467 repo.commit-filter::
 468         Override the default commit-filter. Default value: none. See also:
 469         "enable-filter-overrides". See also: "FILTER API".
 470
 471 repo.commit-sort::
 472         Flag which, when set to "date", enables strict date ordering in the
 473         commit log, and when set to "topo" enables strict topological
 474         ordering. If unset, the default ordering of "git log" is used. Default
 475         value: unset.
 476
 477 repo.defbranch::
 478         The name of the default branch for this repository. If no such branch
 479         exists in the repository, the first branch name (when sorted) is used
 480         as default instead. Default value: branch pointed to by HEAD, or
 481         "master" if there is no suitable HEAD.
 482
 483 repo.desc::
 484         The value to show as repository description. Default value: none.
 485
 486 repo.email-filter::
 487         Override the default email-filter. Default value: none. See also:
 488         "enable-filter-overrides". See also: "FILTER API".
 489
 490 repo.enable-commit-graph::
 491         A flag which can be used to disable the global setting
 492         `enable-commit-graph'. Default value: none.
 493
 494 repo.enable-log-filecount::
 495         A flag which can be used to disable the global setting
 496         `enable-log-filecount'. Default value: none.
 497
 498 repo.enable-log-linecount::
 499         A flag which can be used to disable the global setting
 500         `enable-log-linecount'. Default value: none.
 501
 502 repo.enable-remote-branches::
 503         Flag which, when set to "1", will make cgit display remote branches
 504         in the summary and refs views. Default value: <enable-remote-branches>.
 505
 506 repo.enable-subject-links::
 507         A flag which can be used to override the global setting
 508         `enable-subject-links'. Default value: none.
 509
 510 repo.logo::
 511         Url which specifies the source of an image which will be used as a logo
 512         on this repo's pages. Default value: global logo.
 513
 514 repo.logo-link::
 515         Url loaded when clicking on the cgit logo image. If unspecified the
 516         calculated url of the repository index page will be used. Default
 517         value: global logo-link.
 518
 519 repo.module-link::
 520         Text which will be used as the formatstring for a hyperlink when a
 521         submodule is printed in a directory listing. The arguments for the
 522         formatstring are the path and SHA1 of the submodule commit. Default
 523         value: <module-link>
 524
 525 repo.module-link.<path>::
 526         Text which will be used as the formatstring for a hyperlink when a
 527         submodule with the specified subdirectory path is printed in a
 528         directory listing. The only argument for the formatstring is the SHA1
 529         of the submodule commit. Default value: none.
 530
 531 repo.max-stats::
 532         Override the default maximum statistics period. Valid values are equal
 533         to the values specified for the global "max-stats" setting. Default
 534         value: none.
 535
 536 repo.name::
 537         The value to show as repository name. Default value: <repo.url>.
 538
 539 repo.owner::
 540         A value used to identify the owner of the repository. Default value:
 541         none.
 542
 543 repo.path::
 544         An absolute path to the repository directory. For non-bare repositories
 545         this is the .git-directory. Default value: none.
 546
 547 repo.readme::
 548         A path (relative to <repo.path>) which specifies a file to include
 549         verbatim as the "About" page for this repo. You may also specify a
 550         git refspec by head or by hash by prepending the refspec followed by
 551         a colon. For example, "master:docs/readme.mkd". If the value begins
 552         with a colon, i.e. ":docs/readme.rst", the default branch of the
 553         repository will be used. Sharing any file will expose that entire
 554         directory tree to the "/about/PATH" endpoints, so be sure that there
 555         are no non-public files located in the same directory as the readme
 556         file. Default value: <readme>.
 557
 558 repo.snapshots::
 559         A mask of snapshot formats for this repo that cgit generates links for,
 560         restricted by the global "snapshots" setting. Default value:
 561         <snapshots>.
 562
 563 repo.section::
 564         Override the current section name for this repository. Default value:
 565         none.
 566
 567 repo.source-filter::
 568         Override the default source-filter. Default value: none. See also:
 569         "enable-filter-overrides". See also: "FILTER API".
 570
 571 repo.url::
 572         The relative url used to access the repository. This must be the first
 573         setting specified for each repo. Default value: none.
 574
 575
 576 REPOSITORY-SPECIFIC CGITRC FILE
 577 -------------------------------
 578 When the option "scan-path" is used to auto-discover git repositories, cgit
 579 will try to parse the file "cgitrc" within any found repository. Such a
 580 repo-specific config file may contain any of the repo-specific options
 581 described above, except "repo.url" and "repo.path". Additionally, the "filter"
 582 options are only acknowledged in repo-specific config files when
 583 "enable-filter-overrides" is set to "1".
 584
 585 Note: the "repo." prefix is dropped from the option names in repo-specific
 586 config files, e.g. "repo.desc" becomes "desc".
 587
 588
 589 FILTER API
 590 ----------
 591 By default, filters are separate processes that are executed each time they
 592 are needed.  Alternative technologies may be used by prefixing the filter
 593 specification with the relevant string; available values are:
 594
 595 'exec:'::
 596         The default "one process per filter" mode.
 597
 598 'lua:'::
 599         Executes the script using a built-in Lua interpreter. The script is
 600         loaded once per execution of cgit, and may be called multiple times
 601         during cgit's lifetime, making it a good choice for repeated filters
 602         such as the 'email filter'. It responds to three functions:
 603
 604         'filter_open(argument1, argument2, argument3, ...)'::
 605                 This is called upon activation of the filter for a particular
 606                 set of data.
 607         'filter_write(buffer)'::
 608                 This is called whenever cgit writes data to the webpage.
 609         'filter_close()'::
 610                 This is called when the current filtering operation is
 611                 completed. It must return an integer value. Usually 0
 612                 indicates success.
 613
 614         Additionally, cgit exposes to the Lua the following built-in functions:
 615
 616         'html(str)'::
 617                 Writes 'str' to the webpage.
 618         'html_txt(str)'::
 619                 HTML escapes and writes 'str' to the webpage.
 620         'html_attr(str)'::
 621                 HTML escapes for an attribute and writes "str' to the webpage.
 622         'html_url_path(str)'::
 623                 URL escapes for a path and writes 'str' to the webpage.
 624         'html_url_arg(str)'::
 625                 URL escapes for an argument and writes 'str' to the webpage.
 626         'html_include(file)'::
 627                 Includes 'file' in webpage.
 628
 629
 630 Parameters are provided to filters as follows.
 631
 632 about filter::
 633         This filter is given a single parameter: the filename of the source
 634         file to filter. The filter can use the filename to determine (for
 635         example) the type of syntax to follow when formatting the readme file.
 636         The about text that is to be filtered is available on standard input
 637         and the filtered text is expected on standard output.
 638
 639 commit filter::
 640         This filter is given no arguments. The commit message text that is to
 641         be filtered is available on standard input and the filtered text is
 642         expected on standard output.
 643
 644 email filter::
 645         This filter is given two parameters: the email address of the relevent
 646         author and a string indicating the originating page. The filter will
 647         then receive the text string to format on standard input and is
 648         expected to write to standard output the formatted text to be included
 649         in the page.
 650
 651 source filter::
 652         This filter is given a single parameter: the filename of the source
 653         file to filter. The filter can use the filename to determine (for
 654         example) the syntax highlighting mode. The contents of the source
 655         file that is to be filtered is available on standard input and the
 656         filtered contents is expected on standard output.
 657
 658 auth filter::
 659         The authentication filter receives 12 parameters:
 660           - filter action, explained below, which specifies which action the
 661             filter is called for
 662           - http cookie
 663           - http method
 664           - http referer
 665           - http path
 666           - http https flag
 667           - cgit repo
 668           - cgit page
 669           - cgit url
 670           - cgit login url
 671         When the filter action is "body", this filter must write to output the
 672         HTML for displaying the login form, which POSTs to the login url. When
 673         the filter action is "authenticate-cookie", this filter must validate
 674         the http cookie and return a 0 if it is invalid or 1 if it is invalid,
 675         in the exit code / close function. If the filter action is
 676         "authenticate-post", this filter receives POST'd parameters on
 677         standard input, and should write a complete CGI request, preferably
 678         with a 302 redirect, and write to output one or more "Set-Cookie"
 679         HTTP headers, each followed by a newline.
 680
 681         Please see `filters/simple-authentication.lua` for a clear example
 682         script that may be modified.
 683
 684
 685 All filters are handed the following environment variables:
 686
 687 - CGIT_REPO_URL (from repo.url)
 688 - CGIT_REPO_NAME (from repo.name)
 689 - CGIT_REPO_PATH (from repo.path)
 690 - CGIT_REPO_OWNER (from repo.owner)
 691 - CGIT_REPO_DEFBRANCH (from repo.defbranch)
 692 - CGIT_REPO_SECTION (from repo.section)
 693 - CGIT_REPO_CLONE_URL (from repo.clone-url)
 694
 695 If a setting is not defined for a repository and the corresponding global
 696 setting is also not defined (if applicable), then the corresponding
 697 environment variable will be unset.
 698
 699
 700 MACRO EXPANSION
 701 ---------------
 702 The following cgitrc options support a simple macro expansion feature,
 703 where tokens prefixed with "$" are replaced with the value of a similarly
 704 named environment variable:
 705
 706 - cache-root
 707 - include
 708 - project-list
 709 - scan-path
 710
 711 Macro expansion will also happen on the content of $CGIT_CONFIG, if
 712 defined.
 713
 714 One usage of this feature is virtual hosting, which in its simplest form
 715 can be accomplished by adding the following line to /etc/cgitrc:
 716
 717         include=/etc/cgitrc.d/$HTTP_HOST
 718
 719 The following options are expanded during request processing, and support
 720 the environment variables defined in "FILTER API":
 721
 722 - clone-url
 723 - repo.clone-url
 724
 725
 726 EXAMPLE CGITRC FILE
 727 -------------------
 728
 729 ....
 730 # Enable caching of up to 1000 output entries
 731 cache-size=1000
 732
 733
 734 # Specify some default clone urls using macro expansion
 735 clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL
 736
 737 # Specify the css url
 738 css=/css/cgit.css
 739
 740
 741 # Show owner on index page
 742 enable-index-owner=1
 743
 744
 745 # Allow http transport git clone
 746 enable-http-clone=1
 747
 748
 749 # Show extra links for each repository on the index page
 750 enable-index-links=1
 751
 752
 753 # Enable ASCII art commit history graph on the log pages
 754 enable-commit-graph=1
 755
 756
 757 # Show number of affected files per commit on the log pages
 758 enable-log-filecount=1
 759
 760
 761 # Show number of added/removed lines per commit on the log pages
 762 enable-log-linecount=1
 763
 764
 765 # Sort branches by date
 766 branch-sort=age
 767
 768
 769 # Add a cgit favicon
 770 favicon=/favicon.ico
 771
 772
 773 # Use a custom logo
 774 logo=/img/mylogo.png
 775
 776
 777 # Enable statistics per week, month and quarter
 778 max-stats=quarter
 779
 780
 781 # Set the title and heading of the repository index page
 782 root-title=example.com git repositories
 783
 784
 785 # Set a subheading for the repository index page
 786 root-desc=tracking the foobar development
 787
 788
 789 # Include some more info about example.com on the index page
 790 root-readme=/var/www/htdocs/about.html
 791
 792
 793 # Allow download of tar.gz, tar.bz2 and zip-files
 794 snapshots=tar.gz tar.bz2 zip
 795
 796
 797 ##
 798 ## List of common mimetypes
 799 ##
 800
 801 mimetype.gif=image/gif
 802 mimetype.html=text/html
 803 mimetype.jpg=image/jpeg
 804 mimetype.jpeg=image/jpeg
 805 mimetype.pdf=application/pdf
 806 mimetype.png=image/png
 807 mimetype.svg=image/svg+xml
 808
 809
 810 # Highlight source code with python pygments-based highlighter
 811 source-filter=/var/www/cgit/filters/syntax-highlighting.py
 812
 813 # Format markdown, restructuredtext, manpages, text files, and html files
 814 # through the right converters
 815 about-filter=/var/www/cgit/filters/about-formatting.sh
 816
 817 ##
 818 ## Search for these files in the root of the default branch of repositories
 819 ## for coming up with the about page:
 820 ##
 821 readme=:README.md
 822 readme=:readme.md
 823 readme=:README.mkd
 824 readme=:readme.mkd
 825 readme=:README.rst
 826 readme=:readme.rst
 827 readme=:README.html
 828 readme=:readme.html
 829 readme=:README.htm
 830 readme=:readme.htm
 831 readme=:README.txt
 832 readme=:readme.txt
 833 readme=:README
 834 readme=:readme
 835 readme=:INSTALL.md
 836 readme=:install.md
 837 readme=:INSTALL.mkd
 838 readme=:install.mkd
 839 readme=:INSTALL.rst
 840 readme=:install.rst
 841 readme=:INSTALL.html
 842 readme=:install.html
 843 readme=:INSTALL.htm
 844 readme=:install.htm
 845 readme=:INSTALL.txt
 846 readme=:install.txt
 847 readme=:INSTALL
 848 readme=:install
 849
 850
 851 ##
 852 ## List of repositories.
 853 ## PS: Any repositories listed when section is unset will not be
 854 ##     displayed under a section heading
 855 ## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
 856 ##      and included like this:
 857 ##        include=/etc/cgitrepos
 858 ##
 859
 860
 861 repo.url=foo
 862 repo.path=/pub/git/foo.git
 863 repo.desc=the master foo repository
 864 repo.owner=fooman@example.com
 865 repo.readme=info/web/about.html
 866
 867
 868 repo.url=bar
 869 repo.path=/pub/git/bar.git
 870 repo.desc=the bars for your foo
 871 repo.owner=barman@example.com
 872 repo.readme=info/web/about.html
 873
 874
 875 # The next repositories will be displayed under the 'extras' heading
 876 section=extras
 877
 878
 879 repo.url=baz
 880 repo.path=/pub/git/baz.git
 881 repo.desc=a set of extensions for bar users
 882
 883 repo.url=wiz
 884 repo.path=/pub/git/wiz.git
 885 repo.desc=the wizard of foo
 886
 887
 888 # Add some mirrored repositories
 889 section=mirrors
 890
 891
 892 repo.url=git
 893 repo.path=/pub/git/git.git
 894 repo.desc=the dscm
 895
 896
 897 repo.url=linux
 898 repo.path=/pub/git/linux.git
 899 repo.desc=the kernel
 900
 901 # Disable adhoc downloads of this repo
 902 repo.snapshots=0
 903
 904 # Disable line-counts for this repo
 905 repo.enable-log-linecount=0
 906
 907 # Restrict the max statistics period for this repo
 908 repo.max-stats=month
 909 ....
 910
 911
 912 BUGS
 913 ----
 914 Comments currently cannot appear on the same line as a setting; the comment
 915 will be included as part of the value. E.g. this line:
 916
 917         robots=index  # allow indexing
 918
 919 will generate the following html element:
 920
 921         <meta name='robots' content='index  # allow indexing'/>
 922
 923
 924
 925 AUTHOR
 926 ------
 927 Lars Hjemli <hjemli@gmail.com>
 928 Jason A. Donenfeld <Jason@zx2c4.com>