cgit — Configuration Reference

Configuration File

Default location: /etc/cgitrc (compiled in as CGIT_CONFIG). Override at runtime by setting the $CGIT_CONFIG environment variable.

File Format

The configuration file uses a simple name=value format, parsed by parse_configfile() in configfile.c. Key rules:

• Lines starting with # or ; are comments
• Leading whitespace on lines is skipped
• No quoting mechanism — the value is everything after the = to end of line
• Empty lines are ignored
• Nesting depth for include= directives is limited to 8 levels

int parse_configfile(const char *filename, configfile_value_fn fn)
{
    static int nesting;
    /* ... */
    if (nesting > 8)
        return -1;
    /* ... */
    while (read_config_line(f, &name, &value))
        fn(name.buf, value.buf);
    /* ... */
}

Global Directives

All global directives are processed by config_cb() in cgit.c. When a directive is encountered, the value is stored in the corresponding ctx.cfg.* field.

Site Identity

URL Configuration

When virtual-root is set, URLs use path-based routing: /cgit/repo/log/path. Without it, query-string routing is used: ?url=repo/log/path.

Feature Flags

Limits

Caching

Sorting

Snapshots

Filters

Filter values use the format type:command:

• exec:/path/to/script — external process filter
• lua:/path/to/script.lua — Lua script filter
• Plain path without prefix defaults to exec

Display

Miscellaneous

Repository Directives

Repository configuration begins with repo.url= which creates a new repository entry via cgit_add_repo(). Subsequent repo.* directives modify the most recently created repository via repo_config() in cgit.c.

Filter overrides (require enable-filter-overrides=1)

Repository Defaults

When a new repository is created by cgit_add_repo(), it inherits all global defaults from ctx.cfg:

ret->section = ctx.cfg.section;
ret->snapshots = ctx.cfg.snapshots;
ret->enable_blame = ctx.cfg.enable_blame;
ret->enable_commit_graph = ctx.cfg.enable_commit_graph;
ret->enable_log_filecount = ctx.cfg.enable_log_filecount;
ret->enable_log_linecount = ctx.cfg.enable_log_linecount;
ret->enable_remote_branches = ctx.cfg.enable_remote_branches;
ret->enable_subject_links = ctx.cfg.enable_subject_links;
ret->enable_html_serving = ctx.cfg.enable_html_serving;
ret->enable_subtree = ctx.cfg.enable_subtree;
ret->max_stats = ctx.cfg.max_stats;
ret->max_subtree_commits = ctx.cfg.max_subtree_commits;
ret->branch_sort = ctx.cfg.branch_sort;
ret->commit_sort = ctx.cfg.commit_sort;
ret->module_link = ctx.cfg.module_link;
ret->readme = ctx.cfg.readme;
ret->about_filter = ctx.cfg.about_filter;
ret->commit_filter = ctx.cfg.commit_filter;
ret->source_filter = ctx.cfg.source_filter;
ret->email_filter = ctx.cfg.email_filter;
ret->owner_filter = ctx.cfg.owner_filter;
ret->clone_url = ctx.cfg.clone_url;

This means global directives should appear before repo.url= entries, since they set the defaults for subsequently defined repositories.

Git Config Integration

When enable-git-config=1, the scan-tree scanner reads each repository's .git/config and maps gitweb-compatible directives:

if (!strcmp(key, "gitweb.owner"))
    config_fn(repo, "owner", value);
else if (!strcmp(key, "gitweb.description"))
    config_fn(repo, "desc", value);
else if (!strcmp(key, "gitweb.category"))
    config_fn(repo, "section", value);
else if (!strcmp(key, "gitweb.homepage"))
    config_fn(repo, "homepage", value);
else if (skip_prefix(key, "cgit.", &name))
    config_fn(repo, name, value);

Any cgit.* key in the git config is passed directly to the repo config handler, allowing per-repo settings without modifying the global cgitrc.

README File Spec Format

README directives support three forms:

Multiple readme directives can be specified. cgit tries each in order and uses the first one found (checked via cgit_ref_path_exists() for tracked files, or access(R_OK) for disk files).

Macro Expansion

The expand_macros() function (in shared.c) performs environment variable substitution in certain directive values (cache-root, scan-path, project-list, include). A $VARNAME or ${VARNAME} in the value is replaced with the corresponding environment variable.

Example Configuration

# Site settings
root-title=Project Tick Git
root-desc=Source code for Project Tick
logo=/cgit/cgit.png
css=/cgit/cgit.css
virtual-root=/cgit/

# Features
enable-commit-graph=1
enable-blame=1
enable-http-clone=1
enable-index-links=1
snapshots=tar.gz tar.xz zip
max-stats=quarter

# Caching
cache-size=1000
cache-root=/var/cache/cgit

# Filters
source-filter=exec:/usr/lib/cgit/filters/syntax-highlighting.py
about-filter=exec:/usr/lib/cgit/filters/about-formatting.sh

# Scanning
scan-path=/srv/git/
section-from-path=1

# Or manual repo definitions:
repo.url=myproject
repo.path=/srv/git/myproject.git
repo.desc=My awesome project
repo.owner=Alice
repo.readme=master:README.md
repo.clone-url=https://git.example.com/myproject.git
repo.snapshots=tar.gz zip
repo.badge=https://ci.example.com/badge.svg|https://ci.example.com/