CGITRC(5)

cgitrc - runtime configuration for cgit

Cgitrc contains all runtime settings for cgit, including the list of git repositories, formatted as a line-separated list of NAME=VALUE pairs. Blank lines, and lines starting with #, are ignored.

The default location of cgitrc, defined at compile time, is /etc/cgitrc. At runtime, cgit will consult the environment variable CGIT_CONFIG and, if defined, use its value instead.

When the option "scan-path" is used to auto-discover git repositories, cgit will try to parse the file "cgitrc" within any found repository. Such a repo-specific config file may contain any of the repo-specific options described above, except "repo.url" and "repo.path". Additionally, the "filter" options are only acknowledged in repo-specific config files when "enable-filter-overrides" is set to "1".

Note: the "repo." prefix is dropped from the option names in repo-specific config files, e.g. "repo.desc" becomes "desc".

Also, all filters are handed the following environment variables:

If a setting is not defined for a repository and the corresponding global setting is also not defined (if applicable), then the corresponding environment variable will be unset.

The following cgitrc options supports a simple macro expansion feature, where tokens prefixed with "$" are replaced with the value of a similary named environment variable:

Macro expansion will also happen on the content of $CGIT_CONFIG, if defined.

One usage of this feature is virtual hosting, which in its simplest form can be accomplished by adding the following line to /etc/cgitrc:

include=/etc/cgitrc.d/$HTTP_HOST

The following options are expanded during request processing, and support the environment variables defined in "FILTER API":

# Enable caching of up to 1000 output entriess
cache-size=1000


# Specify some default clone urls using macro expansion
clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL

# Specify the css url
css=/css/cgit.css


# Show owner on index page
enable-index-owner=1


# Allow http transport git clone
enable-git-clone=1


# Show extra links for each repository on the index page
enable-index-links=1


# Enable ASCII art commit history graph on the log pages
enable-commit-graph=1


# Show number of affected files per commit on the log pages
enable-log-filecount=1


# Show number of added/removed lines per commit on the log pages
enable-log-linecount=1


# Sort branches by date
branch-sort=age


# Add a cgit favicon
favicon=/favicon.ico


# Use a custom logo
logo=/img/mylogo.png


# Enable statistics per week, month and quarter
max-stats=quarter


# Set the title and heading of the repository index page
root-title=example.com git repositories


# Set a subheading for the repository index page
root-desc=tracking the foobar development


# Include some more info about example.com on the index page
root-readme=/var/www/htdocs/about.html


# Allow download of tar.gz, tar.bz2 and zip-files
snapshots=tar.gz tar.bz2 zip


##
## List of common mimetypes
##

mimetype.gif=image/gif
mimetype.html=text/html
mimetype.jpg=image/jpeg
mimetype.jpeg=image/jpeg
mimetype.pdf=application/pdf
mimetype.png=image/png
mimetype.svg=image/svg+xml


# Highlight source code with python pygments-based highligher
source-filter=/var/www/cgit/filters/syntax-highlighting.py

# Format markdown, restructuredtext, manpages, text files, and html files
# through the right converters
about-filter=/var/www/cgit/filters/about-formatting.sh

##
## Search for these files in the root of the default branch of repositories
## for coming up with the about page:
##
readme=:README.md
readme=:readme.md
readme=:README.mkd
readme=:readme.mkd
readme=:README.rst
readme=:readme.rst
readme=:README.html
readme=:readme.html
readme=:README.htm
readme=:readme.htm
readme=:README.txt
readme=:readme.txt
readme=:README
readme=:readme
readme=:INSTALL.md
readme=:install.md
readme=:INSTALL.mkd
readme=:install.mkd
readme=:INSTALL.rst
readme=:install.rst
readme=:INSTALL.html
readme=:install.html
readme=:INSTALL.htm
readme=:install.htm
readme=:INSTALL.txt
readme=:install.txt
readme=:INSTALL
readme=:install


##
## List of repositories.
## PS: Any repositories listed when section is unset will not be
##     displayed under a section heading
## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
##      and included like this:
##        include=/etc/cgitrepos
##


repo.url=foo
repo.path=/pub/git/foo.git
repo.desc=the master foo repository
repo.owner=fooman@example.com
repo.readme=info/web/about.html


repo.url=bar
repo.path=/pub/git/bar.git
repo.desc=the bars for your foo
repo.owner=barman@example.com
repo.readme=info/web/about.html


# The next repositories will be displayed under the 'extras' heading
section=extras


repo.url=baz
repo.path=/pub/git/baz.git
repo.desc=a set of extensions for bar users

repo.url=wiz
repo.path=/pub/git/wiz.git
repo.desc=the wizard of foo


# Add some mirrored repositories
section=mirrors


repo.url=git
repo.path=/pub/git/git.git
repo.desc=the dscm


repo.url=linux
repo.path=/pub/git/linux.git
repo.desc=the kernel

# Disable adhoc downloads of this repo
repo.snapshots=0

# Disable line-counts for this repo
repo.enable-log-linecount=0

# Restrict the max statistics period for this repo
repo.max-stats=month

Comments currently cannot appear on the same line as a setting; the comment will be included as part of the value. E.g. this line:

robots=index  # allow indexing

will generate the following html element:

<meta name='robots' content='index  # allow indexing'/>

Lars Hjemli <hjemli@gmail.com> Jason A. Donenfeld <Jason@zx2c4.com>