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