NAME

cgitrc - runtime configuration for cgit

SYNOPSIS

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.

LOCATION

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.

GLOBAL SETTINGS

about-filter

agefile

auth-filter

branch-sort

cache-about-ttl

cache-dynamic-ttl

cache-repo-ttl

cache-root

cache-root-ttl

cache-scanrc-ttl

case-sensitive-sort

cache-size

cache-snapshot-ttl

cache-static-ttl

clone-prefix

clone-url

commit-filter

commit-sort

css

email-filter

embedded

enable-blame

enable-commit-graph

enable-filter-overrides

enable-follow-links

enable-git-config

enable-http-clone

enable-html-serving

enable-index-links

enable-index-owner

enable-log-filecount

enable-log-linecount

enable-remote-branches

enable-subject-links

enable-tree-linenumbers

favicon

footer

head-include

header

include

js

local-time

logo

logo-link

max-atom-items

max-blob-size

max-commit-count

max-message-length

max-repo-count

max-repodesc-length

max-stats

mimetype.<ext>

mimetype-file

module-link

noplainemail

noheader

owner-filter

project-list

readme

remove-suffix

renamelimit

repository-sort

robots

root-desc

root-readme

root-title

scan-hidden-path

scan-path

section

section-sort

section-from-path

side-by-side-diffs

snapshots

source-filter

summary-branches

summary-log

summary-tags

strict-export

virtual-root

REPOSITORY SETTINGS

repo.about-filter

repo.branch-sort

repo.clone-url

repo.commit-filter

repo.commit-sort

repo.defbranch

repo.desc

repo.email-filter

repo.enable-blame

repo.enable-commit-graph

repo.enable-html-serving

repo.enable-log-filecount

repo.enable-log-linecount

repo.enable-remote-branches

repo.enable-subject-links

repo.extra-head-content

repo.hide

repo.homepage

repo.ignore

repo.logo

repo.logo-link

repo.module-link

repo.module-link.<path>

repo.max-stats

repo.name

repo.owner

repo.owner-filter

repo.path

repo.readme

repo.section

repo.snapshots

repo.snapshot-prefix

repo.source-filter

repo.url

REPOSITORY-SPECIFIC CGITRC FILE

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".

FILTER API

By default, filters are separate processes that are executed each time they are needed. Alternative technologies may be used by prefixing the filter specification with the relevant string; available values are:

exec:

lua:

filter_open(argument1, argument2, argument3, ...)

filter_write(buffer)

filter_close()

Additionally, cgit exposes to the Lua the following built-in functions:

html(str)

html_txt(str)

html_attr(str)

html_url_path(str)

html_url_arg(str)

html_include(file)

Parameters are provided to filters as follows.

about filter

auth filter

Please see `filters/simple-authentication.lua` for a clear example
script that may be modified.

commit filter

email filter

owner filter

source filter

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.

MACRO EXPANSION

The following cgitrc options support a simple macro expansion feature, where tokens prefixed with "$" are replaced with the value of a similarly 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":

CACHE

All cache ttl values are in minutes. Negative ttl values indicate that a page type will never expire, and thus the first time a URL is accessed, the result will be cached indefinitely, even if the underlying git repository changes. Conversely, when a ttl value is zero, the cache is disabled for that particular page type, and the page type is never cached.

SIGNATURES

Cgit can host .asc signatures corresponding to various snapshot formats, through use of git notes. For example, the following command may be used to add a signature to a .tar.xz archive:

git notes --ref=refs/notes/signatures/tar.xz add -C "$(
    gpg --output - --armor --detach-sign cgit-1.1.tar.xz |
    git hash-object -w --stdin
)" v1.1

If it is instead desirable to attach a signature of the underlying .tar, this will be linked, as a special case, beside a .tar.* link that does not have its own signature. For example, a signature of a tarball of the latest tag might be added with a similar command:

tag="$(git describe --abbrev=0)"
git notes --ref=refs/notes/signatures/tar add -C "$(
    git archive --format tar --prefix "cgit-${tag#v}/" "$tag" |
    gpg --output - --armor --detach-sign |
    git hash-object -w --stdin
)" "$tag"

Since git-archive(1) is expected to produce stable output between versions, this allows one to generate a long-term signature of the contents of a given tag.

EXAMPLE CGITRC FILE

# Enable caching of up to 1000 output entries
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-http-clone=1
# Show extra links for each repository on the index page
enable-index-links=1
# Enable blame page and create links to it from tree page
enable-blame=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 highlighter
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

BUGS

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'/>

AUTHOR

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