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 favicon::
 103         Url used as link to a shortcut icon for cgit. If specified, it is
 104         suggested to use the value "/favicon.ico" since certain browsers will
 105         ignore other values. Default value: none.
 106
 107 footer::
 108         The content of the file specified with this option will be included
 109         verbatim at the bottom of all pages (i.e. it replaces the standard
 110         "generated by..." message. Default value: none.
 111
 112 head-include::
 113         The content of the file specified with this option will be included
 114         verbatim in the html HEAD section on all pages. Default value: none.
 115
 116 header::
 117         The content of the file specified with this option will be included
 118         verbatim at the top of all pages. Default value: none.
 119
 120 include::
 121         Name of a configfile to include before the rest of the current config-
 122         file is parsed. Default value: none.
 123
 124 index-header::
 125         The content of the file specified with this option will be included
 126         verbatim above the repository index. This setting is deprecated, and
 127         will not be supported by cgit-1.0 (use root-readme instead). Default
 128         value: none.
 129
 130 index-info::
 131         The content of the file specified with this option will be included
 132         verbatim below the heading on the repository index page. This setting
 133         is deprecated, and will not be supported by cgit-1.0 (use root-desc
 134         instead). Default value: none.
 135
 136 local-time::
 137         Flag which, if set to "1", makes cgit print commit and tag times in the
 138         servers timezone. Default value: "0".
 139
 140 logo::
 141         Url which specifies the source of an image which will be used as a logo
 142         on all cgit pages. Default value: "/cgit.png".
 143
 144 logo-link::
 145         Url loaded when clicking on the cgit logo image. If unspecified the
 146         calculated url of the repository index page will be used. Default
 147         value: none.
 148
 149 linenumbers::
 150         If set to "1" lines in tree view will have numbers.
 151         Default value: "0".
 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 (and allowed) set of snapshot formats
 225         supported by cgit. The value is a space-separated list of zero or more
 226         of the following values:
 227                 "tar"           uncompressed tar-file
 228                 "tar.gz"        gzip-compressed tar-file
 229                 "tar.bz2"       bzip-compressed tar-file
 230                 "zip"           zip-file
 231         Default value: none.
 232
 233 source-filter::
 234         Specifies a command which will be invoked to format plaintext blobs
 235         in the tree view. The command will get the blob content on its STDIN
 236         and the name of the blob as its only command line argument. The STDOUT
 237         from the command will be included verbatim as the blob contents, i.e.
 238         this can be used to implement e.g. syntax highlighting. Default value:
 239         none.
 240
 241 summary-branches::
 242         Specifies the number of branches to display in the repository "summary"
 243         view. Default value: "10".
 244
 245 summary-log::
 246         Specifies the number of log entries to display in the repository
 247         "summary" view. Default value: "10".
 248
 249 summary-tags::
 250         Specifies the number of tags to display in the repository "summary"
 251         view. Default value: "10".
 252
 253 virtual-root::
 254         Url which, if specified, will be used as root for all cgit links. It
 255         will also cause cgit to generate 'virtual urls', i.e. urls like
 256         '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
 257         value: none.
 258         NOTE: cgit has recently learned how to use PATH_INFO to achieve the
 259         same kind of virtual urls, so this option will probably be deprecated.
 260
 261 REPOSITORY SETTINGS
 262 -------------------
 263 repo.about-filter::
 264         Override the default about-filter. Default value: <about-filter>.
 265
 266 repo.clone-url::
 267         A list of space-separated urls which can be used to clone this repo.
 268         Default value: none.
 269
 270 repo.commit-filter::
 271         Override the default commit-filter. Default value: <commit-filter>.
 272
 273 repo.defbranch::
 274         The name of the default branch for this repository. If no such branch
 275         exists in the repository, the first branch name (when sorted) is used
 276         as default instead. Default value: "master".
 277
 278 repo.desc::
 279         The value to show as repository description. Default value: none.
 280
 281 repo.enable-log-filecount::
 282         A flag which can be used to disable the global setting
 283         `enable-log-filecount'. Default value: none.
 284
 285 repo.enable-log-linecount::
 286         A flag which can be used to disable the global setting
 287         `enable-log-linecount'. Default value: none.
 288
 289 repo.max-stats::
 290         Override the default maximum statistics period. Valid values are equal
 291         to the values specified for the global "max-stats" setting. Default
 292         value: none.
 293
 294 repo.name::
 295         The value to show as repository name. Default value: <repo.url>.
 296
 297 repo.owner::
 298         A value used to identify the owner of the repository. Default value:
 299         none.
 300
 301 repo.path::
 302         An absolute path to the repository directory. For non-bare repositories
 303         this is the .git-directory. Default value: none.
 304
 305 repo.readme::
 306         A path (relative to <repo.path>) which specifies a file to include
 307         verbatim as the "About" page for this repo. Default value: none.
 308
 309 repo.snapshots::
 310         A mask of allowed snapshot-formats for this repo, restricted by the
 311         "snapshots" global setting. Default value: <snapshots>.
 312
 313 repo.source-filter::
 314         Override the default source-filter. Default value: <source-filter>.
 315
 316 repo.url::
 317         The relative url used to access the repository. This must be the first
 318         setting specified for each repo. Default value: none.
 319
 320
 321 EXAMPLE CGITRC FILE
 322 -------------------
 323
 324 ....
 325 # Enable caching of up to 1000 output entriess
 326 cache-size=1000
 327
 328
 329 # Specify some default clone prefixes
 330 clone-prefix=git://foobar.com ssh://foobar.com/pub/git http://foobar.com/git
 331
 332 # Specify the css url
 333 css=/css/cgit.css
 334
 335
 336 # Show extra links for each repository on the index page
 337 enable-index-links=1
 338
 339
 340 # Show number of affected files per commit on the log pages
 341 enable-log-filecount=1
 342
 343
 344 # Show number of added/removed lines per commit on the log pages
 345 enable-log-linecount=1
 346
 347
 348 # Add a cgit favicon
 349 favicon=/favicon.ico
 350
 351
 352 # Use a custom logo
 353 logo=/img/mylogo.png
 354
 355
 356 # Enable statistics per week, month and quarter
 357 max-stats=quarter
 358
 359
 360 # Set the title and heading of the repository index page
 361 root-title=foobar.com git repositories
 362
 363
 364 # Set a subheading for the repository index page
 365 root-desc=tracking the foobar development
 366
 367
 368 # Include some more info about foobar.com on the index page
 369 root-readme=/var/www/htdocs/about.html
 370
 371
 372 # Allow download of tar.gz, tar.bz2 and zip-files
 373 snapshots=tar.gz tar.bz2 zip
 374
 375
 376 ##
 377 ## List of common mimetypes
 378 ##
 379
 380 mimetype.git=image/git
 381 mimetype.html=text/html
 382 mimetype.jpg=image/jpeg
 383 mimetype.jpeg=image/jpeg
 384 mimetype.pdf=application/pdf
 385 mimetype.png=image/png
 386 mimetype.svg=image/svg+xml
 387
 388
 389 ##
 390 ## List of repositories.
 391 ## PS: Any repositories listed when repo.group is unset will not be
 392 ##     displayed under a group heading
 393 ## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
 394 ##      and included like this:
 395 ##        include=/etc/cgitrepos
 396 ##
 397
 398
 399 repo.url=foo
 400 repo.path=/pub/git/foo.git
 401 repo.desc=the master foo repository
 402 repo.owner=fooman@foobar.com
 403 repo.readme=info/web/about.html
 404
 405
 406 repo.url=bar
 407 repo.path=/pub/git/bar.git
 408 repo.desc=the bars for your foo
 409 repo.owner=barman@foobar.com
 410 repo.readme=info/web/about.html
 411
 412
 413 # The next repositories will be displayed under the 'extras' heading
 414 repo.group=extras
 415
 416
 417 repo.url=baz
 418 repo.path=/pub/git/baz.git
 419 repo.desc=a set of extensions for bar users
 420
 421 repo.url=wiz
 422 repo.path=/pub/git/wiz.git
 423 repo.desc=the wizard of foo
 424
 425
 426 # Add some mirrored repositories
 427 repo.group=mirrors
 428
 429
 430 repo.url=git
 431 repo.path=/pub/git/git.git
 432 repo.desc=the dscm
 433
 434
 435 repo.url=linux
 436 repo.path=/pub/git/linux.git
 437 repo.desc=the kernel
 438
 439 # Disable adhoc downloads of this repo
 440 repo.snapshots=0
 441
 442 # Disable line-counts for this repo
 443 repo.enable-log-linecount=0
 444
 445 # Restrict the max statistics period for this repo
 446 repo.max-stats=month
 447 ....
 448
 449
 450 BUGS
 451 ----
 452 Comments currently cannot appear on the same line as a setting; the comment
 453 will be included as part of the value. E.g. this line:
 454
 455         robots=index  # allow indexing
 456
 457 will generate the following html element:
 458
 459         <meta name='robots' content='index  # allow indexing'/>
 460
 461
 462
 463 AUTHOR
 464 ------
 465 Lars Hjemli <hjemli@gmail.com>