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 module-link::
 164         Text which will be used as the formatstring for a hyperlink when a
 165         submodule is printed in a directory listing. The arguments for the
 166         formatstring are the path and SHA1 of the submodule commit. Default
 167         value: "./?repo=%s&page=commit&id=%s"
 168
 169 nocache::
 170         If set to the value "1" caching will be disabled. This settings is
 171         deprecated, and will not be honored starting with cgit-1.0. Default
 172         value: "0".
 173
 174 noheader::
 175         Flag which, when set to "1", will make cgit omit the standard header
 176         on all pages. Default value: none. See also: "embedded".
 177
 178 renamelimit::
 179         Maximum number of files to consider when detecting renames. The value
 180          "-1" uses the compiletime value in git (for further info, look at
 181           `man git-diff`). Default value: "-1".
 182
 183 repo.group::
 184         A value for the current repository group, which all repositories
 185         specified after this setting will inherit. Default value: none.
 186
 187 robots::
 188         Text used as content for the "robots" meta-tag. Default value:
 189         "index, nofollow".
 190
 191 root-desc::
 192         Text printed below the heading on the repository index page. Default
 193         value: "a fast webinterface for the git dscm".
 194
 195 root-readme::
 196         The content of the file specified with this option will be included
 197         verbatim below the "about" link on the repository index page. Default
 198         value: none.
 199
 200 root-title::
 201         Text printed as heading on the repository index page. Default value:
 202         "Git Repository Browser".
 203
 204 snapshots::
 205         Text which specifies the default (and allowed) set of snapshot formats
 206         supported by cgit. The value is a space-separated list of zero or more
 207         of the following values:
 208                 "tar"           uncompressed tar-file
 209                 "tar.gz"        gzip-compressed tar-file
 210                 "tar.bz2"       bzip-compressed tar-file
 211                 "zip"           zip-file
 212         Default value: none.
 213
 214 source-filter::
 215         Specifies a command which will be invoked to format plaintext blobs
 216         in the tree view. The command will get the blob content on its STDIN
 217         and the name of the blob as its only command line argument. The STDOUT
 218         from the command will be included verbatim as the blob contents, i.e.
 219         this can be used to implement e.g. syntax highlighting. Default value:
 220         none.
 221
 222 summary-branches::
 223         Specifies the number of branches to display in the repository "summary"
 224         view. Default value: "10".
 225
 226 summary-log::
 227         Specifies the number of log entries to display in the repository
 228         "summary" view. Default value: "10".
 229
 230 summary-tags::
 231         Specifies the number of tags to display in the repository "summary"
 232         view. Default value: "10".
 233
 234 virtual-root::
 235         Url which, if specified, will be used as root for all cgit links. It
 236         will also cause cgit to generate 'virtual urls', i.e. urls like
 237         '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default
 238         value: none.
 239         NOTE: cgit has recently learned how to use PATH_INFO to achieve the
 240         same kind of virtual urls, so this option will probably be deprecated.
 241
 242 REPOSITORY SETTINGS
 243 -------------------
 244 repo.about-filter::
 245         Override the default about-filter. Default value: <about-filter>.
 246
 247 repo.clone-url::
 248         A list of space-separated urls which can be used to clone this repo.
 249         Default value: none.
 250
 251 repo.commit-filter::
 252         Override the default commit-filter. Default value: <commit-filter>.
 253
 254 repo.defbranch::
 255         The name of the default branch for this repository. If no such branch
 256         exists in the repository, the first branch name (when sorted) is used
 257         as default instead. Default value: "master".
 258
 259 repo.desc::
 260         The value to show as repository description. Default value: none.
 261
 262 repo.enable-log-filecount::
 263         A flag which can be used to disable the global setting
 264         `enable-log-filecount'. Default value: none.
 265
 266 repo.enable-log-linecount::
 267         A flag which can be used to disable the global setting
 268         `enable-log-linecount'. Default value: none.
 269
 270 repo.max-stats::
 271         Override the default maximum statistics period. Valid values are equal
 272         to the values specified for the global "max-stats" setting. Default
 273         value: none.
 274
 275 repo.name::
 276         The value to show as repository name. Default value: <repo.url>.
 277
 278 repo.owner::
 279         A value used to identify the owner of the repository. Default value:
 280         none.
 281
 282 repo.path::
 283         An absolute path to the repository directory. For non-bare repositories
 284         this is the .git-directory. Default value: none.
 285
 286 repo.readme::
 287         A path (relative to <repo.path>) which specifies a file to include
 288         verbatim as the "About" page for this repo. Default value: none.
 289
 290 repo.snapshots::
 291         A mask of allowed snapshot-formats for this repo, restricted by the
 292         "snapshots" global setting. Default value: <snapshots>.
 293
 294 repo.source-filter::
 295         Override the default source-filter. Default value: <source-filter>.
 296
 297 repo.url::
 298         The relative url used to access the repository. This must be the first
 299         setting specified for each repo. Default value: none.
 300
 301
 302 EXAMPLE CGITRC FILE
 303 -------------------
 304
 305 ....
 306 # Enable caching of up to 1000 output entriess
 307 cache-size=1000
 308
 309
 310 # Specify some default clone prefixes
 311 clone-prefix=git://foobar.com ssh://foobar.com/pub/git http://foobar.com/git
 312
 313 # Specify the css url
 314 css=/css/cgit.css
 315
 316
 317 # Show extra links for each repository on the index page
 318 enable-index-links=1
 319
 320
 321 # Show number of affected files per commit on the log pages
 322 enable-log-filecount=1
 323
 324
 325 # Show number of added/removed lines per commit on the log pages
 326 enable-log-linecount=1
 327
 328
 329 # Add a cgit favicon
 330 favicon=/favicon.ico
 331
 332
 333 # Use a custom logo
 334 logo=/img/mylogo.png
 335
 336
 337 # Enable statistics per week, month and quarter
 338 max-stats=quarter
 339
 340
 341 # Set the title and heading of the repository index page
 342 root-title=foobar.com git repositories
 343
 344
 345 # Set a subheading for the repository index page
 346 root-desc=tracking the foobar development
 347
 348
 349 # Include some more info about foobar.com on the index page
 350 root-readme=/var/www/htdocs/about.html
 351
 352
 353 # Allow download of tar.gz, tar.bz2 and zip-files
 354 snapshots=tar.gz tar.bz2 zip
 355
 356
 357 ##
 358 ## List of repositories.
 359 ## PS: Any repositories listed when repo.group is unset will not be
 360 ##     displayed under a group heading
 361 ## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
 362 ##      and included like this:
 363 ##        include=/etc/cgitrepos
 364 ##
 365
 366
 367 repo.url=foo
 368 repo.path=/pub/git/foo.git
 369 repo.desc=the master foo repository
 370 repo.owner=fooman@foobar.com
 371 repo.readme=info/web/about.html
 372
 373
 374 repo.url=bar
 375 repo.path=/pub/git/bar.git
 376 repo.desc=the bars for your foo
 377 repo.owner=barman@foobar.com
 378 repo.readme=info/web/about.html
 379
 380
 381 # The next repositories will be displayed under the 'extras' heading
 382 repo.group=extras
 383
 384
 385 repo.url=baz
 386 repo.path=/pub/git/baz.git
 387 repo.desc=a set of extensions for bar users
 388
 389 repo.url=wiz
 390 repo.path=/pub/git/wiz.git
 391 repo.desc=the wizard of foo
 392
 393
 394 # Add some mirrored repositories
 395 repo.group=mirrors
 396
 397
 398 repo.url=git
 399 repo.path=/pub/git/git.git
 400 repo.desc=the dscm
 401
 402
 403 repo.url=linux
 404 repo.path=/pub/git/linux.git
 405 repo.desc=the kernel
 406
 407 # Disable adhoc downloads of this repo
 408 repo.snapshots=0
 409
 410 # Disable line-counts for this repo
 411 repo.enable-log-linecount=0
 412
 413 # Restrict the max statistics period for this repo
 414 repo.max-stats=month
 415 ....
 416
 417
 418 BUGS
 419 ----
 420 Comments currently cannot appear on the same line as a setting; the comment
 421 will be included as part of the value. E.g. this line:
 422
 423         robots=index  # allow indexing
 424
 425 will generate the following html element:
 426
 427         <meta name='robots' content='index  # allow indexing'/>
 428
 429
 430
 431 AUTHOR
 432 ------
 433 Lars Hjemli <hjemli@gmail.com>