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