From 061066b77bfa96d9cc9a5ec7693f5777173d6497 Mon Sep 17 00:00:00 2001 From: Bryce Kwon Date: Sun, 6 Sep 2026 15:11:48 -1000 Subject: Convert the manual page to plain `MANUAL.txt` Beyond the format change, the documented defaults and inheritance notes now match what the code does. --- MANUAL.txt | 903 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++ Makefile | 63 +--- README.txt | 4 +- cgitrc.5.txt | 926 ----------------------------------------------------------- 4 files changed, 911 insertions(+), 985 deletions(-) create mode 100644 MANUAL.txt delete mode 100644 cgitrc.5.txt diff --git a/MANUAL.txt b/MANUAL.txt new file mode 100644 index 0000000..4c924cf --- /dev/null +++ b/MANUAL.txt @@ -0,0 +1,903 @@ +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 '#' or ';', are ignored, and so is a line +carrying no '='. A comment cannot share a line with a setting, since everything +after the '=' belongs to the value. A NAME cgit does not recognise is ignored +with a warning on stderr, which the web server collects in its error log. + +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:: + Specifies a command which will be invoked to format the content of about + pages (both top-level and for each repository). The command will get the + content of the about-file on its STDIN, the name of the file as the + first argument, and the STDOUT from the command will be included + verbatim on the about page. Default value: none. When no about-filter is + set, the readme is escaped and served as plain text. A bundled Lua + filter, about-render.lua, renders markdown, man pages and plain text + when about-filter points at it. See also: "Filter API". + +age-file:: + Specifies a path, relative to each repository path, which can be used to + specify the date and time of the youngest commit in the repository. The + first line in the file is used as input to the "parse_date" function in + libgit. Recommended timestamp-format is "yyyy-mm-dd hh:mm:ss". You may + want to generate this file from a post-receive hook. Default value: + "info/web/last-modified". + +auth-filter:: + Specifies a command that will be invoked for authenticating repository + access. Receives 12 arguments, with request data on stdin and its + answer on stdout, as described under "Filter API". If no auth-filter is + specified, no authentication is performed. Default value: none. + +branch-sort:: + Flag which, when set to "age", enables date ordering in the branch ref + list, and when set to "name" enables ordering by branch name. Default + value: "name". + +cache-about-ttl:: + Number which specifies the time-to-live, in minutes, for the cached + version of the repository about page. See also: "The cache". Default + value: "15". + +cache-dynamic-ttl:: + Number which specifies the time-to-live, in minutes, for the cached + version of repository pages accessed without a fixed SHA1. See also: + "The cache". Default value: "5". + +cache-index-ttl:: + Number which specifies the time-to-live, in minutes, for the cached + version of the repository index page. See also: "The cache". Default + value: "5". + +cache-root:: + Path used to store the cgit cache entries. Default value: + "/var/cache/cgit". See also: "Macro expansion" and the note on ownership + under "The cache". + +cache-scan-ttl:: + Number which specifies the time-to-live, in minutes, for the result of + scanning a path for git repositories. See also: "The cache". Default + value: "15". + +cache-size:: + The maximum number of entries in the cgit cache. When set to "0", + caching is disabled. See also: "The cache". Default value: "0". + +cache-snapshot-ttl:: + Number which specifies the time-to-live, in minutes, for the cached + version of snapshots. A snapshot requested with a fixed object id uses + "cache-static-ttl" instead, since its content can never change. See + also: "The cache". Default value: "5". + +cache-static-ttl:: + Number which specifies the time-to-live, in minutes, for the cached + version of repository pages accessed with a fixed SHA1. See also: "The + cache". Default value: "-1". + +cache-summary-ttl:: + Number which specifies the time-to-live, in minutes, for the cached + version of the repository summary page. See also: "The cache". Default + value: "5". + +case-sensitive-sort:: + Sort items in the repo list case sensitively. Default value: "1". See + also: repository-sort, section-sort. + +clone-prefix:: + Space-separated list of common prefixes which, when combined with a + repository url, generates valid clone urls for the repository. This + setting is only used if `repo.clone-url` is unspecified. Default value: + none. + +clone-url:: + Space-separated list of clone-url templates. This setting is only used + if `repo.clone-url` is unspecified. Default value: none. See also: + "Macro expansion", "Filter API". + +commit-filter:: + Specifies a command which will be invoked to format commit messages. The + command will get the message on its STDIN, and the STDOUT from the + command will be included verbatim as the commit message, i.e. this can + be used to implement bugtracker integration. Default value: none. See + also: "Filter API". + +commit-sort:: + Flag which, when set to "date", enables strict date ordering in the + commit log, and when set to "topo" enables strict topological ordering. + If unset, the default ordering of "git log" is used. Default value: + unset. + +css:: + Url which specifies the css document to include in all cgit pages. + Default value: "/cgit.css". May be given multiple times, each css URL + path is added in the head section of the document in turn. Setting this + to an empty string will disable generation of the link to this file in + the head section. + +date-format:: + Format used for the calendar dates in the age columns of the log, refs + and index pages, both when "enable-relative-dates" is off and when a log + entry is too old to be shown as an age. Accepts the same names as git's + --date option: "default", "human", "iso" (or "iso8601"), "iso-strict" + (or "iso8601-strict"), "raw", "relative", "rfc" (or "rfc2822"), "short" + and "unix", each of which may carry a "-local" suffix, plus + "format:" for an arbitrary layout. An unrecognised value is + ignored. Dates elsewhere, such as the author and committer lines on the + commit page, are always ISO 8601 and are not affected, nor are the exact + timestamps shown on hover. Default value: "short". See also: + "local-time". + +email-filter:: + Specifies a command which will be invoked to format names and email + address of committers, authors, and taggers, as represented in various + places throughout the cgit interface. This command will receive an email + address and an origin page string as its command line arguments, and the + text to format on STDIN. It is to write the formatted text back out onto + STDOUT. Default value: none. See also: "Filter API". + +embedded:: + Flag which, when set to "1", will make cgit generate a html fragment + suitable for embedding in other html pages. Default value: "0". See + also: "enable-header". + +enable-blame:: + Flag which, when set to "1", will allow cgit to provide a "blame" page + for files, and will make it generate links to that page in appropriate + places. Default value: "0". + +enable-cache-list:: + Flag which, when set to "1", exposes the "ls_cache" page. That page + lists the cache directory path and the URLs of requests other visitors + made, so it is disabled by default and should stay off on any instance + where that disclosure matters. Default value: "0". + +enable-commit-graph:: + Flag which, when set to "1", will make cgit print an ASCII-art commit + history graph to the left of the commit messages in the repository log + page. Default value: "0". + +enable-filter-overrides:: + Flag which, when set to "1", allows the filter settings to be set per + repository, both as "repo." settings in the main cgitrc and + inside repository-specific cgitrc files. When unset, such settings are + ignored with a warning. Default value: "0". + +enable-follow-links:: + Flag which, when set to "1", allows users to follow a file in the log + view. Default value: "0". + +enable-git-config:: + Flag which, when set to "1", will allow cgit to use git config to set + any repo specific settings. This option is used in conjunction with + "scan-path", and must be defined prior, to augment repo-specific + settings. The keys gitweb.owner, gitweb.category, and gitweb.description + will map to the cgit keys repo.owner, repo.section, and repo.desc + respectively. All git config keys that begin with "cgit." will be mapped + to the corresponding "repo." key in cgit. Default value: "0". See also: + scan-path, section-from-path. + +enable-gitmodules-links:: + Flag which, when set to "1", makes submodule listings derive a link from + the url recorded in the .gitmodules file at the shown revision, for + submodules that no module-link template covers. The url is first + matched, by its trailing path components, against the repositories + served by this cgit instance, so ssh, file and relative urls still get a + link when their target is hosted here, and the commit hash then links to + the target repository's commit page. Otherwise a plain http or https url + is linked as it is, an ssh url to a well-known public host is rewritten + to its https form, and any other url is left unlinked and shown as a + tooltip instead. Default value: "0". See also: + "repo.enable-gitmodules-links". + +enable-header:: + Flag which, when set to "0", makes cgit omit the standard header on all + pages. Default value: "1". See also: "embedded". + +enable-html-serving:: + Flag which, when set to "1", will allow the /plain handler to serve + mimetype headers that result in the file being treated as HTML by the + browser. When set to "0", such file types are returned instead as + text/plain or application/octet-stream. Default value: "0". See also: + "repo.enable-html-serving". + +enable-http-clone:: + If set to "1", cgit will act as a dumb HTTP endpoint for git clones. You + can add "http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL" to clone-url to + expose this feature. If you use an alternate way of serving git + repositories, you may wish to disable this. Default value: "1". + +enable-index-links:: + Flag which, when set to "1", will make cgit generate extra links for + each repo in the repository index (specifically, to the "summary", + "commit" and "tree" pages). Default value: "0". + +enable-index-owner:: + Flag which, when set to "1", will make cgit display the owner of each + repo in the repository index. Default value: "1". + +enable-log-filecount:: + Flag which, when set to "1", will make cgit print the number of modified + files for each commit on the repository log page. Default value: "0". + +enable-log-linecount:: + Flag which, when set to "1", will make cgit print the number of added + and removed lines for each commit on the repository log page. Default + value: "0". + +enable-plain-email:: + Flag which, when set to "0", hides the full author, committer and tagger + email addresses wherever they would be shown beside the name. Default + value: "1". + +enable-relative-dates:: + Flag which, when set to "1", shows the age columns of the log, refs and + index pages as an elapsed time such as "3 days" rather than a calendar + date. When set to "0" those columns always show a date, formatted + according to "date-format". Default value: "1". + +enable-remote-branches:: + Flag which, when set to "1", will make cgit display remote branches in + the summary and refs views. Default value: "0". See also: + "repo.enable-remote-branches". + +enable-subject-links:: + Flag which, when set to "1", will make cgit use the subject of the + parent commit as link text when generating links to parent commits in + commit view. Default value: "0". See also: "repo.enable-subject-links". + +enable-tree-group-dirs:: + Flag which, when set to "1", makes the tree view list all directories + first, sorted, followed by the files. When set to "0", entries appear in + git's own order, with directories and files intermixed by name. Default + value: "0". + +enable-tree-linenumbers:: + Flag which, when set to "1", will make cgit generate linenumber links + for plaintext blobs printed in the tree view. Default value: "1". + +favicon:: + Url used as link to the icon for cgit. Any path works, but keeping the + value "/favicon.ico" is still worthwhile, since clients that do not + parse the page head probe that path directly. Default value: + "/favicon.ico". + +footer:: + The content of the file specified with this option will be included + verbatim at the bottom of all pages (it replaces the standard "generated + by..." message). Default value: none. + +head-include:: + The content of the file specified with this option will be included + verbatim in the html HEAD section on all pages. Default value: none. + +header:: + The content of the file specified with this option will be included + verbatim at the top of all pages. Default value: none. + +include:: + Name of a configfile to include before the rest of the current + configfile is parsed. Includes may nest eight levels deep, and anything + deeper is ignored. Default value: none. See also: "Macro expansion". + +js:: + Url which specifies the javascript script document to include in all + cgit pages. Default value: "/cgit.js". Setting this to an empty string + will disable generation of the link to this file in the head section. + +local-time:: + Flag which, if set to "1", makes cgit print commit and tag times in the + servers timezone. Default value: "0". See also: "date-format". + +logo:: + Url which specifies the source of an image which will be used as a logo + on all cgit pages. Default value: "/cgit.png". + +logo-link:: + Url loaded when clicking on the cgit logo image. If unspecified the + calculated url of the repository index page will be used. Default value: + none. + +max-atom-items:: + Specifies the number of items to display in atom feeds view. Default + value: "10". + +max-blob-size:: + Specifies the maximum size in KBytes of a blob that cgit will read into + memory to serve. It caps both the HTML blob view and the raw "plain" and + "blob" output, and a larger object is refused rather than loaded whole. + Default value: "10240" (10 MB). Set to "0" to disable the limit. + +max-commit-count:: + Specifies the number of entries to list per page in "log" view. Default + value: "50". + +max-diff-files:: + If a commit changes more files than this, the "commit" and "diff" views + show only the diffstat, where each file links to its own diff page. The + "rawdiff" and "patch" views are never limited. Default value: "200". Set + to "0" to always render every file inline. + +max-diff-lines:: + If a single file's diff spans more lines than this, the whole-commit + views print a note in its place linking to the file's own diff page, + which always renders in full. Default value: "1000". Set to "0" to + always render oversized files inline. + +max-message-length:: + Specifies the maximum number of commit message characters to display in + "log" view. Default value: "80". + +max-patch-count:: + Specifies the maximum number of commits emitted as a series by the + "patch" view when an explicit revision range is requested. A single + commit is unaffected. Default value: "50". Set to "0" for no limit. + +max-ref-count:: + Specifies the number of branches and tags to list per section on the + "refs" view, and per page on the dedicated branch and tag pages that its + overflow links lead to. Default value: "200". Set to "0" to list every + ref on one page. + +max-repo-count:: + Specifies the number of entries to list per page on the repository index + page. A value of "0" or less shows all repositories without limitation. + Default value: "50". + +max-repodesc-length:: + Specifies the maximum number of repo description characters to display + on the repository index page. Default value: "80". + +max-stats:: + Enable the statistics page, which holds the commits-per-author table, + and set the coarsest period it offers. Valid values are "week", "month", + "quarter" and "year", each of which also offers the finer periods before + it. If unspecified, statistics are disabled. Default value: none. See + also: "repo.max-stats". + +mimetype-file:: + Specifies the file to use for automatic mimetype lookup. If specified + then this field is used as a fallback when no "mimetype." match is + found. If unspecified then no such lookup is performed. The typical file + to use on a Linux system is /etc/mime.types. The format of the file must + comply to: + - a comment line is an empty line or a line starting with a hash (#), + optionally preceded by whitespace + - a non-comment line starts with the mimetype (like image/png), followed + by one or more file extensions (like jpg), all separated by whitespace + Default value: none. See also: "mimetype.". + +mimetype.:: + Set the mimetype for the specified filename extension. This is used by + the `plain` command when returning blob content. + +module-link:: + Text which will be used as the formatstring for a hyperlink when a + submodule is printed in a directory listing. The arguments for the + formatstring are the name of the submodule directory and the SHA1 of the + submodule commit. Default value: none. + +project-list:: + A list of subdirectories inside of scan-path, relative to it, that + should be loaded as git repositories. This must be defined prior to + scan-path. Default value: none. See also: scan-path, "Macro expansion". + +readme:: + Text which will be used as default value for "repo.readme". Multiple + config keys may be specified, and cgit will use the first found file in + this list. This is useful in conjunction with scan-path. Default value: + none. See also: scan-path, repo.readme. + +remove-suffix:: + If set to "1" and scan-path is enabled, if any repositories are found + with a suffix of ".git", this suffix will be removed for the url and + name. This must be defined prior to scan-path. Default value: "0". See + also: scan-path. + +rename-limit:: + Maximum number of files to consider when detecting renames. The value + "-1" uses the compiletime value in git (for further info, look at `man + git-diff`). Default value: "-1". + +repository-sort:: + The way in which repositories in each section are sorted. Valid values + are "name" for sorting by the repo name or "age" for sorting by the most + recently updated repository. Default value: "name". See also: section, + case-sensitive-sort, section-sort. + +robots:: + Text used as content for the "robots" meta-tag. Default value: "index, + nofollow". + +root-desc:: + Text printed below the heading on the repository index page. Default + value: "a fast webinterface for the git dscm". + +root-readme:: + The content of the file specified with this option will be included + verbatim below the "about" link on the repository index page. Default + value: none. + +root-title:: + Text printed as heading on the repository index page. Default value: + "Git repository browser". + +scan-hidden-path:: + If set to "1" and scan-path is enabled, scan-path will recurse into + directories whose name starts with a period ('.'). Otherwise, scan-path + will stay away from such directories (considered as "hidden"). Note that + this does not apply to the ".git" directory in non-bare repos. This must + be defined prior to scan-path. Default value: "0". See also: scan-path. + +scan-path:: + A path which will be scanned for repositories. If caching is enabled, + the result will be cached as a cgitrc include-file in the cache + directory. If project-list has been defined prior to scan-path, + scan-path loads only the directories listed in the file pointed to by + project-list. A repository containing a file named "noweb" is skipped, + the reverse of what "strict-export" checks. Be advised that only the + global settings taken before the scan-path directive will be applied to + each repository. That holds for every setting a repository inherits, + among them section, snapshots, readme, the filters and the enable flags, + not only the entries that say so explicitly. Default value: none. See + also: cache-scan-ttl, project-list, strict-export, "Macro expansion". + +section:: + The name of the current repository section. All repositories defined + after this option will inherit the current section name. Default value: + none. + +section-from-path:: + A number which, if defined prior to scan-path, specifies how many path + elements from each repo path to use as a default section name. If + negative, cgit will discard the specified number of path elements above + the repo directory. Default value: "0". + +section-sort:: + Flag which, when set to "1", will sort the sections on the repository + listing by name, along with the repositories within each section. Set + this flag to "0" to preserve the order in the cgitrc file. Default + value: "0". See also: section, case-sensitive-sort, repository-sort. + +side-by-side-diffs:: + If set to "1" shows side-by-side diffs instead of unidiffs by default. + Default value: "0". + +snapshots:: + Text which specifies the default set of snapshot formats that cgit + generates links for. The value is a space-separated list of zero or more + of the values "tar", "tar.gz", "tar.bz2", "tar.lz", "tar.xz", "tar.zst" + and "zip". The special value "all" enables all snapshot formats. Default + value: none. All compressors use default settings. Some settings can be + influenced with environment variables, for example set ZSTD_CLEVEL=10 in + web server environment for higher (but slower) zstd compression. + +source-filter:: + Specifies a command which will be invoked to format plaintext blobs in + the tree view. The command will get the blob content on its STDIN and + the name of the blob as its only command line argument. The STDOUT from + the command will be included verbatim as the blob contents, i.e. this + can be used to implement e.g. syntax highlighting. When no source-filter + is configured, cgit serves the text plain. A ready syntax highlighter + using the Scintillua lexer collection ships as + custom/extensions/syntax-highlight.lua, see the comments in that file + for its dependencies. Default value: none. See also: "Filter API". + +strict-export:: + Filename which, if specified, needs to be present within the repository + for cgit to allow access to that repository. This can be used to emulate + gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's + repositories to match those exported by git-daemon. This option must be + defined prior to scan-path. Default value: none. See also: scan-path. + +summary-branches:: + Specifies the number of branches to display in the repository "summary" + view. Default value: "10". + +summary-log:: + Specifies the number of log entries to display in the repository + "summary" view. Default value: "10". + +summary-tags:: + Specifies the number of tags to display in the repository "summary" + view. Default value: "10". + +virtual-root:: + Url which, if specified, will be used as root for all cgit links. It + will also cause cgit to generate 'virtual urls', i.e. urls like + '/cgit/tree/README' as opposed to '?url=cgit/tree/README'. Default + value: none. + + +Repository settings +------------------- + +repo.about-filter:: + Override the default about-filter. Only honoured when + "enable-filter-overrides" is set. Default value: . See + also: "Filter API". + +repo.branch-sort:: + Flag which, when set to "age", enables date ordering in the branch ref + list, and when set to "name" enables ordering by branch name. Default + value: . + +repo.clone-url:: + A list of space-separated urls which can be used to clone this repo. + Default value: . See also: "Macro expansion". + +repo.commit-filter:: + Override the default commit-filter. Only honoured when + "enable-filter-overrides" is set. Default value: . See + also: "Filter API". + +repo.commit-sort:: + Flag which, when set to "date", enables strict date ordering in the + commit log, and when set to "topo" enables strict topological ordering. + If unset, the default ordering of "git log" is used. Default value: + . + +repo.defbranch:: + The name of the default branch for this repository. If no such branch + exists in the repository, the first branch name (when sorted) is used as + default instead. Default value: branch pointed to by HEAD, or "master" + if there is no suitable HEAD. + +repo.desc:: + The value to show as repository description. When repositories are found + by scan-path the description file inside the repository is read as a + fallback, unless it still holds git's "Unnamed repository" boilerplate. + Default value: "[no description]". + +repo.email-filter:: + Override the default email-filter. Only honoured when + "enable-filter-overrides" is set. Default value: . See + also: "Filter API". + +repo.enable-blame:: + A flag which can be used to override the global setting "enable-blame". + Default value: . + +repo.enable-commit-graph:: + A flag which can be used to override the global setting + "enable-commit-graph". Default value: . + +repo.enable-follow-links:: + A flag which can be used to override the global setting + "enable-follow-links". Default value: . + +repo.enable-gitmodules-links:: + A flag which can be used to override the global setting + "enable-gitmodules-links". Default value: . + +repo.enable-html-serving:: + A flag which can be used to override the global setting + "enable-html-serving". Default value: . + +repo.enable-log-filecount:: + A flag which can be used to override the global setting + "enable-log-filecount". Default value: . + +repo.enable-log-linecount:: + A flag which can be used to override the global setting + "enable-log-linecount". Default value: . + +repo.enable-remote-branches:: + A flag which can be used to override the global setting + "enable-remote-branches". Default value: . + +repo.enable-subject-links:: + A flag which can be used to override the global setting + "enable-subject-links". Default value: . + +repo.head-content:: + This value will be added verbatim to the html HEAD section of each page + displayed for this repo. Default value: none. See also: "head-include". + +repo.hide:: + Flag which, when set to "1", hides the repository from the repository + index. The repository can still be accessed by providing a direct path. + Default value: "0". See also: "repo.ignore". + +repo.ignore:: + Flag which, when set to "1", ignores the repository. The repository is + not shown in the index and cannot be accessed by providing a direct + path. Default value: "0". See also: "repo.hide". + +repo.logo:: + Url which specifies the source of an image which will be used as a logo + on this repo's pages. Default value: . + +repo.logo-link:: + Url loaded when clicking on the cgit logo image. If unspecified the + calculated url of the repository index page will be used. Default value: + . + +repo.max-stats:: + Override the default maximum statistics period. Valid values are equal + to the values specified for the global "max-stats" setting, and a value + of "0" disables the statistics page for this repository. Default value: + . + +repo.module-link:: + Text which will be used as the formatstring for a hyperlink when a + submodule is printed in a directory listing. The arguments for the + formatstring are the name of the submodule directory and the SHA1 of the + submodule commit. Default value: . + +repo.module-link.:: + Text which will be used as the formatstring for a hyperlink when a + submodule with the specified subdirectory path is printed in a directory + listing. The only argument for the formatstring is the SHA1 of the + submodule commit. Default value: none. + +repo.name:: + The value to show as repository name. Default value: . + +repo.owner:: + A value used to identify the owner of the repository. When repositories + are found by scan-path the name of the repository directory's owner, as + recorded in the password database, is used as a fallback. Default value: + none. + +repo.path:: + An absolute path to the repository directory. For non-bare repositories + this is the .git-directory. Default value: none. + +repo.readme:: + A path (relative to ) which specifies a file to include + verbatim as the "About" page for this repo. You may also specify a git + refspec by head or by hash by prepending the refspec followed by a + colon. For example, "master:docs/readme.mkd". If the value begins with a + colon, i.e. ":docs/readme.rst", the head given in the query or the + default branch of the repository will be used. Sharing any file will + expose that entire directory tree to the "/about/PATH" endpoints, so be + sure that there are no non-public files located in the same directory as + the readme file. Default value: . + +repo.section:: + Override the current section name for this repository. Default value: +
. + +repo.snapshot-prefix:: + Prefix to use for snapshot links instead of the repository basename. For + example, the "linux-stable" repository may wish to set this to "linux" + so that snapshots are in the format "linux-3.15.4" instead of + "linux-stable-3.15.4". Default value: meaning to use the + repository basename. + +repo.snapshots:: + A mask of snapshot formats for this repo that cgit generates links for. + It is intersected with the global "snapshots" setting, so a repository + can withhold formats but never offer one the global setting does not. + Default value: . + +repo.source-filter:: + Override the default source-filter. Only honoured when + "enable-filter-overrides" is set. Default value: . See + also: "Filter API". + +repo.url:: + The relative url used to access the repository. This must be the first + setting specified for each repo. Default value: none. + + +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. The available values are: + +'exec:':: + The default "one process per filter" mode. + +'lua:':: + Executes the script using a built-in Lua interpreter. The script is + loaded once per execution of cgit, and may be called multiple times + during cgit's lifetime, making it a good choice for repeated filters + such as the 'email filter'. It responds to three functions: + + 'filter_open(argument1, argument2, argument3, ...)':: + This is called upon activation of the filter for a particular + set of data. + 'filter_write(buffer)':: + This is called whenever cgit writes data to the webpage. + 'filter_close()':: + This is called when the current filtering operation is + completed. It must return an integer value. Usually 0 indicates + success. + + Additionally, cgit exposes to the Lua the following built-in functions: + + 'html(str)':: + Writes 'str' to the webpage. + 'html_txt(str)':: + HTML escapes and writes 'str' to the webpage. + 'html_attr(str)':: + HTML escapes for an attribute and writes 'str' to the webpage. + 'html_url_path(str)':: + URL escapes for a path and writes 'str' to the webpage. + 'html_url_arg(str)':: + URL escapes for an argument and writes 'str' to the webpage. + 'html_include(file)':: + Includes 'file' in webpage. + + +Parameters are provided to filters as follows. + +about filter:: + This filter is given a single parameter: the filename of the source file + to filter. The filter can use the filename to determine (for example) + the type of syntax to follow when formatting the readme file. The about + text that is to be filtered is available on standard input and the + filtered text is expected on standard output. + +auth filter:: + The authentication filter receives 12 parameters: + - filter action, explained below, which specifies which action the + filter is called for + - http cookie + - http method + - http query string + - http referer + - http path + - http host + - http https flag + - cgit repo + - cgit page + - cgit url + - cgit login url + When the filter action is "body", this filter must write to output the + HTML for displaying the login form, which POSTs to the login url. When + the filter action is "authenticate-cookie", this filter must validate + the http cookie and return a 0 if it is invalid or 1 if it is valid, in + the exit code / close function. If the filter action is + "authenticate-post", this filter receives POST'd parameters on standard + input, and should write a complete CGI response, preferably with a 302 + redirect, and write to output one or more "Set-Cookie" HTTP headers, + each followed by a newline. + + See `custom/extensions/auth-inline.lua` for a ready to modify example + that keeps its user list inline, or `custom/extensions/auth-file.lua` + for the same filter reading its users from files on disk. + +commit filter:: + This filter is given no arguments. The commit message text that is to be + filtered is available on standard input and the filtered text is + expected on standard output. + +email filter:: + This filter is given two parameters: the email address of the relevant + author and a string indicating the originating page. The filter will + then receive the text string to format on standard input and is expected + to write to standard output the formatted text to be included in the + page. + +source filter:: + This filter is given a single parameter: the filename of the source file + to filter. The filter can use the filename to determine (for example) + the syntax highlighting mode. The contents of the source file that is to + be filtered is available on standard input and the filtered contents is + expected on standard output. + + +All filters are handed the following environment variables: + +- CGIT_REPO_URL (from repo.url) +- CGIT_REPO_NAME (from repo.name) +- CGIT_REPO_PATH (from repo.path) +- CGIT_REPO_OWNER (from repo.owner) +- CGIT_REPO_DEFBRANCH (from repo.defbranch) +- CGIT_REPO_SECTION (from repo.section) +- CGIT_REPO_CLONE_URL (from repo.clone-url) + +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: + +- cache-root +- include +- project-list +- scan-path + +Macro expansion will also happen on the content of $CGIT_CONFIG, if defined. + +The set of available variables is not fixed by cgit. The options above are +expanded while the configuration is parsed, against whatever environment the web +server hands the cgit process, so any variable the server sets can be used. A +CGI server provides the standard request variables, among them $HTTP_HOST, +$HTTPS, $PATH_INFO, $QUERY_STRING, $REQUEST_METHOD, $SCRIPT_NAME, $SERVER_NAME +and $SERVER_PORT, and server directives such as SetEnv (Apache), fastcgi_param +(nginx) or setenv.add-environment (lighttpd) can add anything else. Note that +cgit unsets $HOME and $XDG_CONFIG_HOME before reading its configuration, so +those two never expand. + +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 later, during request processing, and +additionally support the seven CGIT_REPO_* variables defined in "Filter API": + +- clone-url +- repo.clone-url + + +The 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. + +The cache directory holds one file per slot plus transient lock files, all +created by cgit itself. Create the directory ahead of time, owned by the account +the web server runs cgit as, with mode 0700. cgit creates its files by name +without guarding against links planted beside them, so a directory other +accounts can write to would let those accounts redirect the writes. A directory +other accounts can read exposes every cached page along with the URLs visitors +asked for. + + +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. diff --git a/Makefile b/Makefile index 6324880..c0d6f7d 100644 --- a/Makefile +++ b/Makefile @@ -1,8 +1,8 @@ -# The entry point for building, documenting and installing cgit. The program -# itself is compiled inside the bundled Git tree by source/cgit.mk, which this -# file invokes with the paths and the defaults it needs. Everything that is not -# compilation, that is the manual page, the install and uninstall rules and the -# housekeeping targets, is driven from here. +# The entry point for building and installing cgit. The program itself is +# compiled inside the bundled Git tree by source/cgit.mk, which this file +# invokes with the paths and the defaults it needs. Everything that is not +# compilation, that is the install and uninstall rules and the housekeeping +# targets, is driven from here. .DEFAULT_GOAL := all .SUFFIXES: @@ -39,28 +39,13 @@ CACHE_ROOT = /var/cache/cgit prefix = /usr/local libdir = $(prefix)/lib filterdir = $(libdir)/cgit/filters -docdir = $(prefix)/share/doc/cgit -htmldir = $(docdir) -mandir = $(prefix)/share/man # The files that go into the data path and the filter directory. One list each # drives both install and uninstall, so the two can never drift apart. ASSETS = cgit.css cgit.js cgit.png favicon.ico robots.txt FILTER_FILES = $(notdir $(wildcard $(EXTDIR)/*.lua)) -# The manual page source, *.5.txt, sits at the project root and is rendered -# into build/. Only one man section exists, so both document lists derive -# straight from MAN5_TXT. -MAN5_TXT = $(wildcard *.5.txt) -DOC_MAN5 = $(patsubst %.txt,$(BUILDDIR)/%,$(MAN5_TXT)) -DOC_HTML = $(patsubst %.txt,$(BUILDDIR)/%.html,$(MAN5_TXT)) - INSTALL = install -ASCIIDOC = asciidoc -ASCIIDOC_EXTRA = -ASCIIDOC_HTML = xhtml11 -ASCIIDOC_COMMON = $(ASCIIDOC) $(ASCIIDOC_EXTRA) -TXT_TO_HTML = $(ASCIIDOC_COMMON) -b $(ASCIIDOC_HTML) # Reuse Git's platform detection, then let the user override any of the # settings above through cgit.conf. Both includes must stay after the defaults. @@ -94,18 +79,6 @@ test: cgit-with-git cgit-with-git: +@$(MAKE) cgit EXTRA_GIT_TARGETS=all -doc: doc-man doc-html -doc-man: $(DOC_MAN5) -doc-html: $(DOC_HTML) - -$(DOC_MAN5): $(BUILDDIR)/%.5 : %.5.txt - @mkdir -p $(BUILDDIR) - a2x -f manpage -D $(BUILDDIR) $< - -$(DOC_HTML): $(BUILDDIR)/%.html : %.txt - @mkdir -p $(BUILDDIR) - $(TXT_TO_HTML) -o $@ $< - install: all $(INSTALL) -m 0755 -d $(DESTDIR)$(CGIT_SCRIPT_PATH) $(INSTALL) -m 0755 $(BUILDDIR)/cgit $(DESTDIR)$(CGIT_SCRIPT_PATH)/$(CGIT_SCRIPT_NAME) @@ -114,33 +87,11 @@ install: all $(INSTALL) -m 0755 -d $(DESTDIR)$(filterdir) $(INSTALL) -m 0644 $(EXTDIR)/*.lua $(DESTDIR)$(filterdir) -install-doc: install-man install-html - -install-man: doc-man - $(INSTALL) -m 0755 -d $(DESTDIR)$(mandir)/man5 - $(INSTALL) -m 0644 $(DOC_MAN5) $(DESTDIR)$(mandir)/man5 - -install-html: doc-html - $(INSTALL) -m 0755 -d $(DESTDIR)$(htmldir) - $(INSTALL) -m 0644 $(DOC_HTML) $(DESTDIR)$(htmldir) - uninstall: $(RM) $(DESTDIR)$(CGIT_SCRIPT_PATH)/$(CGIT_SCRIPT_NAME) $(RM) $(addprefix $(DESTDIR)$(CGIT_DATA_PATH)/,$(ASSETS)) $(RM) $(addprefix $(DESTDIR)$(filterdir)/,$(FILTER_FILES)) -uninstall-doc: uninstall-man uninstall-html - -uninstall-man: - @for i in $(notdir $(DOC_MAN5)); do \ - rm -fv $(DESTDIR)$(mandir)/man5/$$i; \ - done - -uninstall-html: - @for i in $(notdir $(DOC_HTML)); do \ - rm -fv $(DESTDIR)$(htmldir)/$$i; \ - done - # Compiled output lives under build/ and the test suite writes into tests/, so # cleaning removes both. The descent into tests is guarded because # tests/Makefile includes git's config.mak.uname, which needs the submodule @@ -162,7 +113,5 @@ tags: # Grouped to mirror the order of the targets above. .PHONY: all cgit cgit-with-git sparse test -.PHONY: doc doc-man doc-html -.PHONY: install install-doc install-man install-html -.PHONY: uninstall uninstall-doc uninstall-man uninstall-html +.PHONY: install uninstall .PHONY: clean cleanall get-git tags diff --git a/README.txt b/README.txt index d0953a2..d8f16d2 100644 --- a/README.txt +++ b/README.txt @@ -209,8 +209,8 @@ Runtime configuration The file `/etc/cgitrc` is read by cgit before handling a request. In addition to runtime parameters, this file may also contain a list of repositories displayed -by cgit (see `cgitrc.5.txt` for further details). A fully commented starting -point with every option at its default is in `custom/cgitrc`. +by cgit (see `MANUAL.txt` for further details). A fully commented starting point +with every option at its default is in `custom/cgitrc`. The cache diff --git a/cgitrc.5.txt b/cgitrc.5.txt deleted file mode 100644 index b05f6e9..0000000 --- a/cgitrc.5.txt +++ /dev/null @@ -1,926 +0,0 @@ -:man source: cgit -:man manual: cgit - -CGITRC(5) -======== - - -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:: - Specifies a command which will be invoked to format the content of - about pages (both top-level and for each repository). The command will - get the content of the about-file on its STDIN, the name of the file - as the first argument, and the STDOUT from the command will be - included verbatim on the about page. Default value: none. When no - about-filter is set, the readme is escaped and served as plain text. - A bundled Lua filter, about-render.lua, renders markdown, man pages - and plain text when about-filter points at it. See also: "FILTER API". - -agefile:: - Specifies a path, relative to each repository path, which can be used - to specify the date and time of the youngest commit in the repository. - The first line in the file is used as input to the "parse_date" - function in libgit. Recommended timestamp-format is "yyyy-mm-dd - hh:mm:ss". You may want to generate this file from a post-receive - hook. Default value: "info/web/last-modified". - -auth-filter:: - Specifies a command that will be invoked for authenticating repository - access. Receives quite a few arguments, and data on both stdin and - stdout for authentication processing. Details follow later in this - document. If no auth-filter is specified, no authentication is - performed. Default value: none. See also: "FILTER API". - -branch-sort:: - Flag which, when set to "age", enables date ordering in the branch ref - list, and when set to "name" enables ordering by branch name. Default - value: "name". - -cache-about-ttl:: - Number which specifies the time-to-live, in minutes, for the cached - version of the repository about page. See also: "CACHE". Default - value: "15". - -cache-dynamic-ttl:: - Number which specifies the time-to-live, in minutes, for the cached - version of repository pages accessed without a fixed SHA1. See also: - "CACHE". Default value: "5". - -cache-repo-ttl:: - Number which specifies the time-to-live, in minutes, for the cached - version of the repository summary page. See also: "CACHE". Default - value: "5". - -cache-root:: - Path used to store the cgit cache entries. Default value: - "/var/cache/cgit". See also: "MACRO EXPANSION" and the note on - ownership under "CACHE". - -cache-root-ttl:: - Number which specifies the time-to-live, in minutes, for the cached - version of the repository index page. See also: "CACHE". Default - value: "5". - -cache-scanrc-ttl:: - Number which specifies the time-to-live, in minutes, for the result - of scanning a path for git repositories. See also: "CACHE". Default - value: "15". - -case-sensitive-sort:: - Sort items in the repo list case sensitively. Default value: "1". - See also: repository-sort, section-sort. - -cache-size:: - The maximum number of entries in the cgit cache. When set to "0", - caching is disabled. See also: "CACHE". Default value: "0" - -cache-snapshot-ttl:: - Number which specifies the time-to-live, in minutes, for the cached - version of snapshots. A snapshot requested with a fixed object id - uses "cache-static-ttl" instead, since its content can never change. - See also: "CACHE". Default value: "5". - -cache-static-ttl:: - Number which specifies the time-to-live, in minutes, for the cached - version of repository pages accessed with a fixed SHA1. See also: - "CACHE". Default value: -1". - -clone-prefix:: - Space-separated list of common prefixes which, when combined with a - repository url, generates valid clone urls for the repository. This - setting is only used if `repo.clone-url` is unspecified. Default value: - none. - -clone-url:: - Space-separated list of clone-url templates. This setting is only - used if `repo.clone-url` is unspecified. Default value: none. See - also: "MACRO EXPANSION", "FILTER API". - -commit-filter:: - Specifies a command which will be invoked to format commit messages. - The command will get the message on its STDIN, and the STDOUT from the - command will be included verbatim as the commit message, i.e. this can - be used to implement bugtracker integration. Default value: none. - See also: "FILTER API". - -commit-sort:: - Flag which, when set to "date", enables strict date ordering in the - commit log, and when set to "topo" enables strict topological - ordering. If unset, the default ordering of "git log" is used. Default - value: unset. - -css:: - Url which specifies the css document to include in all cgit pages. - Default value: "/cgit.css". May be given multiple times, each - css URL path is added in the head section of the document in turn. - -date-format:: - Format used for the calendar dates in the age columns of the log, refs - and index pages, both when "enable-relative-dates" is off and when a - log entry is too old to be shown as an age. Accepts the same names as - git's --date option: "default", "human", "iso" (or "iso8601"), - "iso-strict" (or "iso8601-strict"), "raw", "relative", "rfc" (or - "rfc2822"), "short" and "unix", each of which may carry a "-local" - suffix, plus "format:" for an arbitrary layout. An - unrecognised value is ignored. Dates elsewhere, such as the author and - committer lines on the commit page, are always ISO 8601 and are not - affected, nor are the exact timestamps shown on hover. Default - value: "short". See also: "local-time". - -email-filter:: - Specifies a command which will be invoked to format names and email - address of committers, authors, and taggers, as represented in various - places throughout the cgit interface. This command will receive an - email address and an origin page string as its command line arguments, - and the text to format on STDIN. It is to write the formatted text back - out onto STDOUT. Default value: none. See also: "FILTER API". - -embedded:: - Flag which, when set to "1", will make cgit generate a html fragment - suitable for embedding in other html pages. Default value: none. See - also: "noheader". - -enable-blame:: - Flag which, when set to "1", will allow cgit to provide a "blame" page - for files, and will make it generate links to that page in appropriate - places. Default value: "0". - -enable-commit-graph:: - Flag which, when set to "1", will make cgit print an ASCII-art commit - history graph to the left of the commit messages in the repository - log page. Default value: "0". - -enable-filter-overrides:: - Flag which, when set to "1", allows all filter settings to be - overridden in repository-specific cgitrc files. Default value: none. - -enable-cache-list:: - Flag which, when set to "1", exposes the "ls_cache" page. That page - lists the cache directory path and the URLs of requests other visitors - made, so it is disabled by default and should stay off on any instance - where that disclosure matters. Default value: "0". - -enable-follow-links:: - Flag which, when set to "1", allows users to follow a file in the log - view. Default value: "0". - -enable-git-config:: - Flag which, when set to "1", will allow cgit to use git config to set - any repo specific settings. This option is used in conjunction with - "scan-path", and must be defined prior, to augment repo-specific - settings. The keys gitweb.owner, gitweb.category, and - gitweb.description will map to the cgit keys repo.owner, repo.section, - and repo.desc respectively. All git config keys that begin - with "cgit." will be mapped to the corresponding "repo." key in cgit. - Default value: "0". See also: scan-path, section-from-path. - -enable-gitmodules-links:: - Flag which, when set to "1", makes submodule listings derive a link - from the url recorded in the .gitmodules file at the shown revision, - for submodules that no module-link template covers. The url is first - matched, by its trailing path components, against the repositories - served by this cgit instance, so ssh, file and relative urls still - get a link when their target is hosted here, and the commit hash then - links to the target repository's commit page. Otherwise a plain http - or https url is linked as it is, an ssh url to a well-known public - host is rewritten to its https form, and any other url is left - unlinked and shown as a tooltip instead. Default value: "0". See - also: "repo.enable-gitmodules-links". - -enable-http-clone:: - If set to "1", cgit will act as a dumb HTTP endpoint for git clones. - You can add "http://$HTTP_HOST$SCRIPT_NAME/$CGIT_REPO_URL" to clone-url - to expose this feature. If you use an alternate way of serving git - repositories, you may wish to disable this. Default value: "1". - -enable-html-serving:: - Flag which, when set to "1", will allow the /plain handler to serve - mimetype headers that result in the file being treated as HTML by the - browser. When set to "0", such file types are returned instead as - text/plain or application/octet-stream. Default value: "0". See also: - "repo.enable-html-serving". - -enable-index-links:: - Flag which, when set to "1", will make cgit generate extra links for - each repo in the repository index (specifically, to the "summary", - "commit" and "tree" pages). Default value: "0". - -enable-index-owner:: - Flag which, when set to "1", will make cgit display the owner of - each repo in the repository index. Default value: "1". - -enable-log-filecount:: - Flag which, when set to "1", will make cgit print the number of - modified files for each commit on the repository log page. Default - value: "0". - -enable-log-linecount:: - Flag which, when set to "1", will make cgit print the number of added - and removed lines for each commit on the repository log page. Default - value: "0". - -enable-relative-dates:: - Flag which, when set to "1", shows the age columns of the log, refs and - index pages as an elapsed time such as "3 days" rather than a calendar - date. When set to "0" those columns always show a date, formatted - according to "date-format". Default value: "1". - -enable-remote-branches:: - Flag which, when set to "1", will make cgit display remote branches - in the summary and refs views. Default value: "0". See also: - "repo.enable-remote-branches". - -enable-stats:: - Flag which, when set to "1", enables the statistics page, which - holds the commits-per-author table. Default value: "0". See also: - "repo.enable-stats", "max-stats". - -enable-subject-links:: - Flag which, when set to "1", will make cgit use the subject of the - parent commit as link text when generating links to parent commits - in commit view. Default value: "0". See also: - "repo.enable-subject-links". - -enable-tree-linenumbers:: - Flag which, when set to "1", will make cgit generate linenumber links - for plaintext blobs printed in the tree view. Default value: "1". - -enable-tree-group-dirs:: - Flag which, when set to "1", makes the tree view list all directories - first, sorted, followed by the files. When set to "0", entries appear - in git's own order, with directories and files intermixed by name. - Default value: "0". - -favicon:: - Url used as link to the icon for cgit. Any path works, but keeping - the value "/favicon.ico" is still worthwhile, since clients that do - not parse the page head probe that path directly. Default value: - "/favicon.ico". - -footer:: - The content of the file specified with this option will be included - verbatim at the bottom of all pages (i.e. it replaces the standard - "generated by..." message. Default value: none. - -head-include:: - The content of the file specified with this option will be included - verbatim in the html HEAD section on all pages. Default value: none. - -header:: - The content of the file specified with this option will be included - verbatim at the top of all pages. Default value: none. - -include:: - Name of a configfile to include before the rest of the current config- - file is parsed. Default value: none. See also: "MACRO EXPANSION". - -js:: - Url which specifies the javascript script document to include in all cgit - pages. Default value: "/cgit.js". Setting this to an empty string will - disable generation of the link to this file in the head section. - -local-time:: - Flag which, if set to "1", makes cgit print commit and tag times in the - servers timezone. Default value: "0". See also: "date-format". - -logo:: - Url which specifies the source of an image which will be used as a logo - on all cgit pages. Default value: "/cgit.png". - -logo-link:: - Url loaded when clicking on the cgit logo image. If unspecified the - calculated url of the repository index page will be used. Default - value: none. - -max-atom-items:: - Specifies the number of items to display in atom feeds view. Default - value: "10". - -max-blob-size:: - Specifies the maximum size in KBytes of a blob that cgit will read into - memory to serve. It caps both the HTML blob view and the raw "plain" and - "blob" output, and a larger object is refused rather than loaded whole. - Default value: "10240" (10 MB). Set to "0" to disable the limit. - -max-commit-count:: - Specifies the number of entries to list per page in "log" view. Default - value: "50". - -max-diff-files:: - If a commit changes more files than this, the "commit" and "diff" - views show only the diffstat, where each file links to its own diff - page. The "rawdiff" and "patch" views are never limited. Default - value: "200". Set to "0" to always render every file inline. - -max-diff-lines:: - If a single file's diff spans more lines than this, the whole-commit - views print a note in its place linking to the file's own diff page, - which always renders in full. Default value: "1000". Set to "0" to - always render oversized files inline. - -max-message-length:: - Specifies the maximum number of commit message characters to display in - "log" view. Default value: "80". - -max-patch-count:: - Specifies the maximum number of commits emitted as a series by the - "patch" view when an explicit revision range is requested. A single - commit is unaffected. Default value: "50". Set to "0" for no limit. - -max-ref-count:: - Specifies the number of branches and tags to list per section on the - "refs" view, and per page on the dedicated branch and tag pages that - its overflow links lead to. Default value: "200". Set to "0" to list - every ref on one page. - -max-repo-count:: - Specifies the number of entries to list per page on the repository - index page. The value "0" shows all repositories without limitation. - Default value: "50". - -max-repodesc-length:: - Specifies the maximum number of repo description characters to display - on the repository index page. Default value: "80". - -max-stats:: - Bound the coarsest period selectable on the statistics page. Valid - values are "week", "month", "quarter" and "year". Unset, every - period is offered. This option no longer enables the page, that is - what "enable-stats" does. Default value: none. See also: - "enable-stats", "repo.max-stats". - -mimetype.:: - Set the mimetype for the specified filename extension. This is used - by the `plain` command when returning blob content. - -mimetype-file:: - Specifies the file to use for automatic mimetype lookup. If specified - then this field is used as a fallback when no "mimetype." match is - found. If unspecified then no such lookup is performed. The typical file - to use on a Linux system is /etc/mime.types. The format of the file must - comply to: - - a comment line is an empty line or a line starting with a hash (#), - optionally preceded by whitespace - - a non-comment line starts with the mimetype (like image/png), followed - by one or more file extensions (like jpg), all separated by whitespace - Default value: none. See also: "mimetype.". - -module-link:: - Text which will be used as the formatstring for a hyperlink when a - submodule is printed in a directory listing. The arguments for the - formatstring are the name of the submodule directory and the SHA1 of - the submodule commit. Default value: none. - -noplainemail:: - If set to "1" showing full author email addresses will be disabled. - Default value: "0". - -noheader:: - Flag which, when set to "1", will make cgit omit the standard header - on all pages. Default value: none. See also: "embedded". - -project-list:: - A list of subdirectories inside of scan-path, relative to it, that - should loaded as git repositories. This must be defined prior to - scan-path. Default value: none. See also: scan-path, "MACRO - EXPANSION". - -readme:: - Text which will be used as default value for "repo.readme". Multiple - config keys may be specified, and cgit will use the first found file - in this list. This is useful in conjunction with scan-path. Default - value: none. See also: scan-path, repo.readme. - -remove-suffix:: - If set to "1" and scan-path is enabled, if any repositories are found - with a suffix of ".git", this suffix will be removed for the url and - name. This must be defined prior to scan-path. Default value: "0". - See also: scan-path. - -renamelimit:: - Maximum number of files to consider when detecting renames. The value - "-1" uses the compiletime value in git (for further info, look at - `man git-diff`). Default value: "-1". - -repository-sort:: - The way in which repositories in each section are sorted. Valid values - are "name" for sorting by the repo name or "age" for sorting by the - most recently updated repository. Default value: "name". See also: - section, case-sensitive-sort, section-sort. - -robots:: - Text used as content for the "robots" meta-tag. Default value: - "index, nofollow". - -root-desc:: - Text printed below the heading on the repository index page. Default - value: "a fast webinterface for the git dscm". - -root-readme:: - The content of the file specified with this option will be included - verbatim below the "about" link on the repository index page. Default - value: none. - -root-title:: - Text printed as heading on the repository index page. Default value: - "Git Repository Browser". - -scan-hidden-path:: - If set to "1" and scan-path is enabled, scan-path will recurse into - directories whose name starts with a period ('.'). Otherwise, - scan-path will stay away from such directories (considered as - "hidden"). Note that this does not apply to the ".git" directory in - non-bare repos. This must be defined prior to scan-path. - Default value: 0. See also: scan-path. - -scan-path:: - A path which will be scanned for repositories. If caching is enabled, - the result will be cached as a cgitrc include-file in the cache - directory. If project-list has been defined prior to scan-path, - scan-path loads only the directories listed in the file pointed to by - project-list. Be advised that only the global settings taken - before the scan-path directive will be applied to each repository. - Default value: none. See also: cache-scanrc-ttl, project-list, - "MACRO EXPANSION". - -section:: - The name of the current repository section - all repositories defined - after this option will inherit the current section name. Default value: - none. - -section-sort:: - Flag which, when set to "1", will sort the sections on the repository - listing by name, along with the repositories within each section. Set - this flag to "0" to preserve the order in the cgitrc file. Default - value: "0". See also: section, case-sensitive-sort, repository-sort. - -section-from-path:: - A number which, if defined prior to scan-path, specifies how many - path elements from each repo path to use as a default section name. - If negative, cgit will discard the specified number of path elements - above the repo directory. Default value: "0". - -side-by-side-diffs:: - If set to "1" shows side-by-side diffs instead of unidiffs per - default. Default value: "0". - -snapshots:: - Text which specifies the default set of snapshot formats that cgit - generates links for. The value is a space-separated list of zero or - more of the values "tar", "tar.gz", "tar.bz2", "tar.lz", "tar.xz", - "tar.zst" and "zip". The special value "all" enables all snapshot - formats. Default value: none. - All compressors use default settings. Some settings can be influenced - with environment variables, for example set ZSTD_CLEVEL=10 in web - server environment for higher (but slower) zstd compression. - -source-filter:: - Specifies a command which will be invoked to format plaintext blobs - in the tree view. The command will get the blob content on its STDIN - and the name of the blob as its only command line argument. The STDOUT - from the command will be included verbatim as the blob contents, i.e. - this can be used to implement e.g. syntax highlighting. When no - source-filter is configured, cgit serves the text plain. A ready - syntax highlighter using the Scintillua lexer collection ships as - custom/extensions/syntax-highlight.lua, see the comments in that file for - its dependencies. Default value: none. See also: "FILTER API". - -summary-branches:: - Specifies the number of branches to display in the repository "summary" - view. Default value: "10". - -summary-log:: - Specifies the number of log entries to display in the repository - "summary" view. Default value: "10". - -summary-tags:: - Specifies the number of tags to display in the repository "summary" - view. Default value: "10". - -strict-export:: - Filename which, if specified, needs to be present within the repository - for cgit to allow access to that repository. This can be used to emulate - gitweb's EXPORT_OK and STRICT_EXPORT functionality and limit cgit's - repositories to match those exported by git-daemon. This option must - be defined prior to scan-path. - -virtual-root:: - Url which, if specified, will be used as root for all cgit links. It - will also cause cgit to generate 'virtual urls', i.e. urls like - '/cgit/tree/README' as opposed to '?r=cgit&p=tree&path=README'. Default - value: none. - NOTE: cgit has recently learned how to use PATH_INFO to achieve the - same kind of virtual urls, so this option will probably be deprecated. - - -REPOSITORY SETTINGS -------------------- -repo.about-filter:: - Override the default about-filter. Default value: none. See also: - "enable-filter-overrides". See also: "FILTER API". - -repo.branch-sort:: - Flag which, when set to "age", enables date ordering in the branch ref - list, and when set to "name" enables ordering by branch name. Default - value: "name". - -repo.clone-url:: - A list of space-separated urls which can be used to clone this repo. - Default value: none. See also: "MACRO EXPANSION". - -repo.commit-filter:: - Override the default commit-filter. Default value: none. See also: - "enable-filter-overrides". See also: "FILTER API". - -repo.commit-sort:: - Flag which, when set to "date", enables strict date ordering in the - commit log, and when set to "topo" enables strict topological - ordering. If unset, the default ordering of "git log" is used. Default - value: unset. - -repo.defbranch:: - The name of the default branch for this repository. If no such branch - exists in the repository, the first branch name (when sorted) is used - as default instead. Default value: branch pointed to by HEAD, or - "master" if there is no suitable HEAD. - -repo.desc:: - The value to show as repository description. Default value: none. - -repo.email-filter:: - Override the default email-filter. Default value: none. See also: - "enable-filter-overrides". See also: "FILTER API". - -repo.enable-blame:: - A flag which can be used to disable the global setting - `enable-blame'. Default value: none. - -repo.enable-commit-graph:: - A flag which can be used to disable the global setting - `enable-commit-graph'. Default value: none. - -repo.enable-follow-links:: - A flag which can be used to disable the global setting - `enable-follow-links'. Default value: none. - -repo.enable-gitmodules-links:: - A flag which can be used to override the global setting - `enable-gitmodules-links'. Default value: none. - -repo.enable-html-serving:: - A flag which can be used to override the global setting - `enable-html-serving`. Default value: none. - -repo.enable-log-filecount:: - A flag which can be used to disable the global setting - `enable-log-filecount'. Default value: none. - -repo.enable-log-linecount:: - A flag which can be used to disable the global setting - `enable-log-linecount'. Default value: none. - -repo.enable-remote-branches:: - Flag which, when set to "1", will make cgit display remote branches - in the summary and refs views. Default value: . - -repo.enable-stats:: - A flag which can be used to override the global setting - `enable-stats'. Default value: none. - -repo.enable-subject-links:: - A flag which can be used to override the global setting - `enable-subject-links'. Default value: none. - -repo.extra-head-content:: - This value will be added verbatim to the head section of each page - displayed for this repo. Default value: none. - -repo.hide:: - Flag which, when set to "1", hides the repository from the repository - index. The repository can still be accessed by providing a direct path. - Default value: "0". See also: "repo.ignore". - -repo.ignore:: - Flag which, when set to "1", ignores the repository. The repository - is not shown in the index and cannot be accessed by providing a direct - path. Default value: "0". See also: "repo.hide". - -repo.logo:: - Url which specifies the source of an image which will be used as a logo - on this repo's pages. Default value: global logo. - -repo.logo-link:: - Url loaded when clicking on the cgit logo image. If unspecified the - calculated url of the repository index page will be used. Default - value: global logo-link. - -repo.module-link:: - Text which will be used as the formatstring for a hyperlink when a - submodule is printed in a directory listing. The arguments for the - formatstring are the name of the submodule directory and the SHA1 of - the submodule commit. Default value: - -repo.module-link.:: - Text which will be used as the formatstring for a hyperlink when a - submodule with the specified subdirectory path is printed in a - directory listing. The only argument for the formatstring is the SHA1 - of the submodule commit. Default value: none. - -repo.max-stats:: - Override the default maximum statistics period. Valid values are equal - to the values specified for the global "max-stats" setting. Default - value: none. - -repo.name:: - The value to show as repository name. Default value: . - -repo.owner:: - A value used to identify the owner of the repository. Default value: - none. - -repo.path:: - An absolute path to the repository directory. For non-bare repositories - this is the .git-directory. Default value: none. - -repo.readme:: - A path (relative to ) which specifies a file to include - verbatim as the "About" page for this repo. You may also specify a - git refspec by head or by hash by prepending the refspec followed by - a colon. For example, "master:docs/readme.mkd". If the value begins - with a colon, i.e. ":docs/readme.rst", the head giving in query or - the default branch of the repository will be used. Sharing any file - will expose that entire directory tree to the "/about/PATH" endpoints, - so be sure that there are no non-public files located in the same - directory as the readme file. Default value: . - -repo.section:: - Override the current section name for this repository. Default value: - none. - -repo.snapshots:: - A mask of snapshot formats for this repo that cgit generates links for, - restricted by the global "snapshots" setting. Default value: - . - -repo.snapshot-prefix:: - Prefix to use for snapshot links instead of the repository basename. - For example, the "linux-stable" repository may wish to set this to - "linux" so that snapshots are in the format "linux-3.15.4" instead - of "linux-stable-3.15.4". Default value: meaning to use - the repository basename. - -repo.source-filter:: - Override the default source-filter. Default value: none. See also: - "enable-filter-overrides". See also: "FILTER API". - -repo.url:: - The relative url used to access the repository. This must be the first - setting specified for each repo. Default value: none. - - -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:':: - The default "one process per filter" mode. - -'lua:':: - Executes the script using a built-in Lua interpreter. The script is - loaded once per execution of cgit, and may be called multiple times - during cgit's lifetime, making it a good choice for repeated filters - such as the 'email filter'. It responds to three functions: - - 'filter_open(argument1, argument2, argument3, ...)':: - This is called upon activation of the filter for a particular - set of data. - 'filter_write(buffer)':: - This is called whenever cgit writes data to the webpage. - 'filter_close()':: - This is called when the current filtering operation is - completed. It must return an integer value. Usually 0 - indicates success. - - Additionally, cgit exposes to the Lua the following built-in functions: - - 'html(str)':: - Writes 'str' to the webpage. - 'html_txt(str)':: - HTML escapes and writes 'str' to the webpage. - 'html_attr(str)':: - HTML escapes for an attribute and writes "str' to the webpage. - 'html_url_path(str)':: - URL escapes for a path and writes 'str' to the webpage. - 'html_url_arg(str)':: - URL escapes for an argument and writes 'str' to the webpage. - 'html_include(file)':: - Includes 'file' in webpage. - - -Parameters are provided to filters as follows. - -about filter:: - This filter is given a single parameter: the filename of the source - file to filter. The filter can use the filename to determine (for - example) the type of syntax to follow when formatting the readme file. - The about text that is to be filtered is available on standard input - and the filtered text is expected on standard output. - -auth filter:: - The authentication filter receives 12 parameters: - - filter action, explained below, which specifies which action the - filter is called for - - http cookie - - http method - - http referer - - http path - - http https flag - - cgit repo - - cgit page - - cgit url - - cgit login url - When the filter action is "body", this filter must write to output the - HTML for displaying the login form, which POSTs to the login url. When - the filter action is "authenticate-cookie", this filter must validate - the http cookie and return a 0 if it is invalid or 1 if it is valid, - in the exit code / close function. If the filter action is - "authenticate-post", this filter receives POST'd parameters on - standard input, and should write a complete CGI response, preferably - with a 302 redirect, and write to output one or more "Set-Cookie" - HTTP headers, each followed by a newline. - - See `custom/extensions/auth-inline.lua` for a ready to modify example that - keeps its user list inline, or `custom/extensions/auth-file.lua` for the - same filter reading its users from files on disk. - -commit filter:: - This filter is given no arguments. The commit message text that is to - be filtered is available on standard input and the filtered text is - expected on standard output. - -email filter:: - This filter is given two parameters: the email address of the relevant - author and a string indicating the originating page. The filter will - then receive the text string to format on standard input and is - expected to write to standard output the formatted text to be included - in the page. - -source filter:: - This filter is given a single parameter: the filename of the source - file to filter. The filter can use the filename to determine (for - example) the syntax highlighting mode. The contents of the source - file that is to be filtered is available on standard input and the - filtered contents is expected on standard output. - - -All filters are handed the following environment variables: - -- CGIT_REPO_URL (from repo.url) -- CGIT_REPO_NAME (from repo.name) -- CGIT_REPO_PATH (from repo.path) -- CGIT_REPO_OWNER (from repo.owner) -- CGIT_REPO_DEFBRANCH (from repo.defbranch) -- CGIT_REPO_SECTION (from repo.section) -- CGIT_REPO_CLONE_URL (from repo.clone-url) - -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: - -- cache-root -- include -- project-list -- scan-path - -Macro expansion will also happen on the content of $CGIT_CONFIG, if -defined. - -The set of available variables is not fixed by cgit. The options above are -expanded while the configuration is parsed, against whatever environment -the web server hands the cgit process, so any variable the server sets can -be used. A CGI server provides the standard request variables, among them -$HTTP_HOST, $HTTPS, $PATH_INFO, $QUERY_STRING, $REQUEST_METHOD, -$SCRIPT_NAME, $SERVER_NAME and $SERVER_PORT, and server directives such as -SetEnv (Apache), fastcgi_param (nginx) or setenv.add-environment -(lighttpd) can add anything else. Note that cgit unsets $HOME and -$XDG_CONFIG_HOME before reading its configuration, so those two never -expand. - -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 later, during request processing, and -additionally support the seven CGIT_REPO_* variables defined in -"FILTER API": - -- clone-url -- repo.clone-url - - -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. - -The cache directory holds one file per slot plus transient lock files, all -created by cgit itself. Create the directory ahead of time, owned by the -account the web server runs cgit as, with mode 0700. cgit creates its files -by name without guarding against links planted beside them, so a directory -other accounts can write to would let those accounts redirect the writes. -A directory other accounts can read exposes every cached page along with -the URLs visitors asked for. - -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. - - -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: - - - - - -AUTHOR ------- -Lars Hjemli -Jason A. Donenfeld -- cgit v2.8.0