gitweb.ps.run Git - ps-cgit/blob - cgitrc.5.txt

   1 CGITRC(5)
   2 ========
   3
   4
   5 NAME
   6 ----
   7 cgitrc - runtime configuration for cgit
   8
   9
  10 SYNOPSIS
  11 --------
  12 Cgitrc contains all runtime settings for cgit, including the list of git
  13 repositories, formatted as a line-separated list of NAME=VALUE pairs. Blank
  14 lines, and lines starting with '#', are ignored.
  15
  16
  17 LOCATION
  18 --------
  19 The default location of cgitrc, defined at compile time, is /etc/cgitrc. At
  20 runtime, cgit will consult the environment variable CGIT_CONFIG and, if
  21 defined, use its value instead.
  22
  23
  24 GLOBAL SETTINGS
  25 ---------------
  26 about-filter::
  27         Specifies a command which will be invoked to format the content of
  28         about pages (both top-level and for each repository). The command will
  29         get the content of the about-file on its STDIN, and the STDOUT from the
  30         command will be included verbatim on the about page. Default value:
  31         none.
  32
  33 agefile::
  34         Specifies a path, relative to each repository path, which can be used
  35         to specify the date and time of the youngest commit in the repository.
  36         The first line in the file is used as input to the "parse_date"
  37         function in libgit. Recommended timestamp-format is "yyyy-mm-dd
  38         hh:mm:ss". Default value: "info/web/last-modified".
  39
  40 cache-root::
  41         Path used to store the cgit cache entries. Default value:
  42         "/var/cache/cgit".
  43
  44 cache-dynamic-ttl::
  45         Number which specifies the time-to-live, in minutes, for the cached
  46         version of repository pages accessed without a fixed SHA1. Default
  47         value: "5".
  48
  49 cache-repo-ttl::
  50         Number which specifies the time-to-live, in minutes, for the cached
  51         version of the repository summary page. Default value: "5".
  52
  53 cache-root-ttl::
  54         Number which specifies the time-to-live, in minutes, for the cached
  55         version of the repository index page. Default value: "5".
  56
  57 cache-size::
  58         The maximum number of entries in the cgit cache. Default value: "0"
  59         (i.e. caching is disabled).
  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. Default value:
  64         "5".
  65
  66 clone-prefix::
  67         Space-separated list of common prefixes which, when combined with a
  68         repository url, generates valid clone urls for the repository. This
  69         setting is only used if `repo.clone-url` is unspecified. Default value:
  70         none.
  71
  72 commit-filter::
  73         Specifies a command which will be invoked to format commit messages.
  74         The command will get the message on its STDIN, and the STDOUT from the
  75         command will be included verbatim as the commit message, i.e. this can
  76         be used to implement bugtracker integration. Default value: none.
  77
  78 css::
  79         Url which specifies the css document to include in all cgit pages.
  80         Default value: "/cgit.css".
  81
  82 embedded::
  83         Flag which, when set to "1", will make cgit generate a html fragment
  84         suitable for embedding in other html pages. Default value: none. See
  85         also: "noheader".
  86
  87 enable-index-links::
  88         Flag which, when set to "1", will make cgit generate extra links for
  89         each repo in the repository index (specifically, to the "summary",
  90         "commit" and "tree" pages). Default value: "0".
  91
  92 enable-log-filecount::
  93         Flag which, when set to "1", will make cgit print the number of
  94         modified files for each commit on the repository log page. Default
  95         value: "0".
  96
  97 enable-log-linecount::
  98         Flag which, when set to "1", will make cgit print the number of added
  99         and removed lines for each commit on the repository log page. Default
 100         value: "0".
 101
 102 enable-tree-linenumbers::
 103         Flag which, when set to "1", will make cgit generate linenumber links
 104         for plaintext blobs printed in the tree view. Default value: "1".
 105
 106 favicon::
 107         Url used as link to a shortcut icon for cgit. If specified, it is
 108         suggested to use the value "/favicon.ico" since certain browsers will
 109         ignore other values. Default value: none.
 110
 111 footer::
 112         The content of the file specified with this option will be included
 113         verbatim at the bottom of all pages (i.e. it replaces the standard
 114         "generated by..." message. Default value: none.
 115
 116 head-include::
 117         The content of the file specified with this option will be included
 118         verbatim in the html HEAD section on all pages. Default value: none.
 119
 120 header::
 121         The content of the file specified with this option will be included
 122         verbatim at the top of all pages. Default value: none.
 123
 124 include::
 125         Name of a configfile to include before the rest of the current config-
 126         file is parsed. Default value: none.
 127
 128 index-header::
 129         The content of the file specified with this option will be included
 130         verbatim above the repository index. This setting is deprecated, and
 131         will not be supported by cgit-1.0 (use root-readme instead). Default
 132         value: none.
 133
 134 index-info::
 135         The content of the file specified with this option will be included
 136         verbatim below the heading on the repository index page. This setting
 137         is deprecated, and will not be supported by cgit-1.0 (use root-desc
 138         instead). Default value: none.
 139
 140 local-time::
 141         Flag which, if set to "1", makes cgit print commit and tag times in the
 142         servers timezone. Default value: "0".
 143
 144 logo::
 145         Url which specifies the source of an image which will be used as a logo
 146         on all cgit pages. Default value: "/cgit.png".
 147
 148 logo-link::
 149         Url loaded when clicking on the cgit logo image. If unspecified the
 150         calculated url of the repository index page will be used. Default
 151         value: none.
 152
 153 max-commit-count::
 154         Specifies the number of entries to list per page in "log" view. Default
 155         value: "50".
 156
 157 max-message-length::
 158         Specifies the maximum number of commit message characters to display in
 159         "log" view. Default value: "80".
 160
 161 max-repo-count::
 162         Specifies the number of entries to list per page on the repository
 163         index page. Default value: "50".
 164
 165 max-repodesc-length::
 166         Specifies the maximum number of repo description characters to display
 167         on the repository index page. Default value: "80".
 168
 169 max-stats::
 170         Set the default maximum statistics period. Valid values are "week",
 171         "month", "quarter" and "year". If unspecified, statistics are
 172         disabled. Default value: none. See also: "repo.max-stats".
 173
 174 mimetype.<ext>::
 175         Set the mimetype for the specified filename extension. This is used
 176         by the `plain` command when returning blob content.
 177
 178 module-link::
 179         Text which will be used as the formatstring for a hyperlink when a
 180         submodule is printed in a directory listing. The arguments for the
 181         formatstring are the path and SHA1 of the submodule commit. Default
 182         value: "./?repo=%s&page=commit&id=%s"
 183
 184 nocache::
 185         If set to the value "1" caching will be disabled. This settings is
 186         deprecated, and will not be honored starting with cgit-1.0. Default
 187         value: "0".
 188
 189 noplainemail::
 190         If set to "1" showing full author email adresses will be disabled.
 191         Default value: "0".
 192
 193 noheader::
 194         Flag which, when set to "1", will make cgit omit the standard header
 195         on all pages. Default value: none. See also: "embedded".
 196
 197 renamelimit::
 198         Maximum number of files to consider when detecting renames. The value
 199          "-1" uses the compiletime value in git (for further info, look at
 200           `man git-diff`). Default value: "-1".
 201
 202 repo.group::
 203         A value for the current repository group, which all repositories
 204         specified after this setting will inherit. Default value: none.
 205
 206 robots::
 207         Text used as content for the "robots" meta-tag. Default value:
 208         "index, nofollow".
 209
 210 root-desc::
 211         Text printed below the heading on the repository index page. Default
 212         value: "a fast webinterface for the git dscm".
 213
 214 root-readme::
 215         The content of the file specified with this option will be included
 216         verbatim below the "about" link on the repository index page. Default
 217         value: none.
 218
 219 root-title::
 220         Text printed as heading on the repository index page. Default value:
 221         "Git Repository Browser".
 222
 223 snapshots::
 224         Text which specifies the default set of snapshot formats generated by
 225         cgit. The value is a space-separated list of zero or more of the
 226         values "tar", "tar.gz", "tar.bz2" and "zip". Default value: none.
 227
 228 source-filter::
 229         Specifies a command which will be invoked to format plaintext blobs
 230         in the tree view. The command will get the blob content on its STDIN
 231         and the name of the blob as its only command line argument. The STDOUT
 232         from the command will be included verbatim as the blob contents, i.e.
 233         this can be used to implement e.g. syntax highlighting. Default value:
 234         none.
 235
 236 summary-branches::
 237         Specifies the number of branches to display in the repository "summary"
 238         view. Default value: "10".
 239
 240 summary-log::
 241         Specifies the number of log entries to display in the repository
 242         "summary" view. Default value: "10".
 243
 244 summary-tags::
 245         Specifies the number of tags to display in the repository "summary"
 246         view. Default value: "10".
 247
 248 virtual-root::
 249         Url which, if specified, will be used as root for all cgit links. It
 250         will also cause cgit to generate 'virtual urls', i.e. urls like
 251         '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
 252         value: none.
 253         NOTE: cgit has recently learned how to use PATH_INFO to achieve the
 254         same kind of virtual urls, so this option will probably be deprecated.
 255
 256 REPOSITORY SETTINGS
 257 -------------------
 258 repo.about-filter::
 259         Override the default about-filter. Default value: <about-filter>.
 260
 261 repo.clone-url::
 262         A list of space-separated urls which can be used to clone this repo.
 263         Default value: none.
 264
 265 repo.commit-filter::
 266         Override the default commit-filter. Default value: <commit-filter>.
 267
 268 repo.defbranch::
 269         The name of the default branch for this repository. If no such branch
 270         exists in the repository, the first branch name (when sorted) is used
 271         as default instead. Default value: "master".
 272
 273 repo.desc::
 274         The value to show as repository description. Default value: none.
 275
 276 repo.enable-log-filecount::
 277         A flag which can be used to disable the global setting
 278         `enable-log-filecount'. Default value: none.
 279
 280 repo.enable-log-linecount::
 281         A flag which can be used to disable the global setting
 282         `enable-log-linecount'. Default value: none.
 283
 284 repo.max-stats::
 285         Override the default maximum statistics period. Valid values are equal
 286         to the values specified for the global "max-stats" setting. Default
 287         value: none.
 288
 289 repo.name::
 290         The value to show as repository name. Default value: <repo.url>.
 291
 292 repo.owner::
 293         A value used to identify the owner of the repository. Default value:
 294         none.
 295
 296 repo.path::
 297         An absolute path to the repository directory. For non-bare repositories
 298         this is the .git-directory. Default value: none.
 299
 300 repo.readme::
 301         A path (relative to <repo.path>) which specifies a file to include
 302         verbatim as the "About" page for this repo. Default value: none.
 303
 304 repo.snapshots::
 305         A mask of allowed snapshot-formats for this repo, restricted by the
 306         "snapshots" global setting. Default value: <snapshots>.
 307
 308 repo.source-filter::
 309         Override the default source-filter. Default value: <source-filter>.
 310
 311 repo.url::
 312         The relative url used to access the repository. This must be the first
 313         setting specified for each repo. Default value: none.
 314
 315
 316 EXAMPLE CGITRC FILE
 317 -------------------
 318
 319 ....
 320 # Enable caching of up to 1000 output entriess
 321 cache-size=1000
 322
 323
 324 # Specify some default clone prefixes
 325 clone-prefix=git://foobar.com ssh://foobar.com/pub/git http://foobar.com/git
 326
 327 # Specify the css url
 328 css=/css/cgit.css
 329
 330
 331 # Show extra links for each repository on the index page
 332 enable-index-links=1
 333
 334
 335 # Show number of affected files per commit on the log pages
 336 enable-log-filecount=1
 337
 338
 339 # Show number of added/removed lines per commit on the log pages
 340 enable-log-linecount=1
 341
 342
 343 # Add a cgit favicon
 344 favicon=/favicon.ico
 345
 346
 347 # Use a custom logo
 348 logo=/img/mylogo.png
 349
 350
 351 # Enable statistics per week, month and quarter
 352 max-stats=quarter
 353
 354
 355 # Set the title and heading of the repository index page
 356 root-title=foobar.com git repositories
 357
 358
 359 # Set a subheading for the repository index page
 360 root-desc=tracking the foobar development
 361
 362
 363 # Include some more info about foobar.com on the index page
 364 root-readme=/var/www/htdocs/about.html
 365
 366
 367 # Allow download of tar.gz, tar.bz2 and zip-files
 368 snapshots=tar.gz tar.bz2 zip
 369
 370
 371 ##
 372 ## List of common mimetypes
 373 ##
 374
 375 mimetype.git=image/git
 376 mimetype.html=text/html
 377 mimetype.jpg=image/jpeg
 378 mimetype.jpeg=image/jpeg
 379 mimetype.pdf=application/pdf
 380 mimetype.png=image/png
 381 mimetype.svg=image/svg+xml
 382
 383
 384 ##
 385 ## List of repositories.
 386 ## PS: Any repositories listed when repo.group is unset will not be
 387 ##     displayed under a group heading
 388 ## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
 389 ##      and included like this:
 390 ##        include=/etc/cgitrepos
 391 ##
 392
 393
 394 repo.url=foo
 395 repo.path=/pub/git/foo.git
 396 repo.desc=the master foo repository
 397 repo.owner=fooman@foobar.com
 398 repo.readme=info/web/about.html
 399
 400
 401 repo.url=bar
 402 repo.path=/pub/git/bar.git
 403 repo.desc=the bars for your foo
 404 repo.owner=barman@foobar.com
 405 repo.readme=info/web/about.html
 406
 407
 408 # The next repositories will be displayed under the 'extras' heading
 409 repo.group=extras
 410
 411
 412 repo.url=baz
 413 repo.path=/pub/git/baz.git
 414 repo.desc=a set of extensions for bar users
 415
 416 repo.url=wiz
 417 repo.path=/pub/git/wiz.git
 418 repo.desc=the wizard of foo
 419
 420
 421 # Add some mirrored repositories
 422 repo.group=mirrors
 423
 424
 425 repo.url=git
 426 repo.path=/pub/git/git.git
 427 repo.desc=the dscm
 428
 429
 430 repo.url=linux
 431 repo.path=/pub/git/linux.git
 432 repo.desc=the kernel
 433
 434 # Disable adhoc downloads of this repo
 435 repo.snapshots=0
 436
 437 # Disable line-counts for this repo
 438 repo.enable-log-linecount=0
 439
 440 # Restrict the max statistics period for this repo
 441 repo.max-stats=month
 442 ....
 443
 444
 445 BUGS
 446 ----
 447 Comments currently cannot appear on the same line as a setting; the comment
 448 will be included as part of the value. E.g. this line:
 449
 450         robots=index  # allow indexing
 451
 452 will generate the following html element:
 453
 454         <meta name='robots' content='index  # allow indexing'/>
 455
 456
 457
 458 AUTHOR
 459 ------
 460 Lars Hjemli <hjemli@gmail.com>