cgitrc.5.txt

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