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