X-Git-Url: https://gitweb.ps.run/ps-cgit/blobdiff_plain/c4d46c7035d07070ac1ebf0c0b44df927358687f..f072bc55b08675db93b2f892016e83d9f975dea2:/cgitrc.5.txt diff --git a/cgitrc.5.txt b/cgitrc.5.txt index 7256ec0..0c13485 100644 --- a/cgitrc.5.txt +++ b/cgitrc.5.txt @@ -1,3 +1,6 @@ +:man source: cgit +:man manual: cgit + CGITRC(5) ======== @@ -14,8 +17,22 @@ 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, and the STDOUT from the + command will be included verbatim on the about page. Default value: + none. + 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. @@ -40,6 +57,10 @@ cache-root-ttl:: Number which specifies the time-to-live, in minutes, for the cached version of the repository index page. 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. Default value: "15". + cache-size:: The maximum number of entries in the cgit cache. Default value: "0" (i.e. caching is disabled). @@ -55,6 +76,12 @@ clone-prefix:: setting is only used if `repo.clone-url` is unspecified. Default value: none. +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. + css:: Url which specifies the css document to include in all cgit pages. Default value: "/cgit.css". @@ -64,6 +91,10 @@ embedded:: suitable for embedding in other html pages. Default value: none. See also: "noheader". +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-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", @@ -79,6 +110,10 @@ enable-log-linecount:: and removed lines for each commit on the repository log page. 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 a shortcut icon for cgit. If specified, it is suggested to use the value "/favicon.ico" since certain browsers will @@ -119,7 +154,7 @@ local-time:: logo:: Url which specifies the source of an image which will be used as a logo - on all cgit pages. + on all cgit pages. Default value: "/cgit.png". logo-link:: Url loaded when clicking on the cgit logo image. If unspecified the @@ -162,6 +197,10 @@ nocache:: deprecated, and will not be honored starting with cgit-1.0. Default value: "0". +noplainemail:: + If set to "1" showing full author email adresses 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". @@ -172,8 +211,8 @@ renamelimit:: `man git-diff`). Default value: "-1". repo.group:: - A value for the current repository group, which all repositories - specified after this setting will inherit. Default value: none. + Legacy alias for "section". This option is deprecated and will not be + supported in cgit-1.0. robots:: Text used as content for the "robots" meta-tag. Default value: @@ -192,15 +231,28 @@ root-title:: Text printed as heading on the repository index page. Default value: "Git Repository Browser". +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. Default value: none. See also: cache-scanrc-ttl. + +section:: + The name of the current repository section - all repositories defined + after this option will inherit the current section name. Default value: + none. + snapshots:: - Text which specifies the default (and allowed) set of snapshot formats - supported by cgit. The value is a space-separated list of zero or more - of the following values: - "tar" uncompressed tar-file - "tar.gz" gzip-compressed tar-file - "tar.bz2" bzip-compressed tar-file - "zip" zip-file - Default value: none. + Text which specifies the default set of snapshot formats generated by + cgit. The value is a space-separated list of zero or more of the + values "tar", "tar.gz", "tar.bz2" and "zip". Default value: none. + +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. Default value: + none. summary-branches:: Specifies the number of branches to display in the repository "summary" @@ -224,10 +276,18 @@ virtual-root:: REPOSITORY SETTINGS ------------------- +repo.about-filter:: + Override the default about-filter. Default value: none. See also: + "enable-filter-overrides". + repo.clone-url:: A list of space-separated urls which can be used to clone this repo. Default value: none. +repo.commit-filter:: + Override the default commit-filter. Default value: none. See also: + "enable-filter-overrides". + 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 @@ -268,11 +328,32 @@ repo.snapshots:: A mask of allowed snapshot-formats for this repo, restricted by the "snapshots" global setting. Default value: . +repo.section:: + Override the current section name for this repository. Default value: + none. + +repo.source-filter:: + Override the default source-filter. Default value: none. See also: + "enable-filter-overrides". + 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". + + EXAMPLE CGITRC FILE ------------------- @@ -343,8 +424,8 @@ mimetype.svg=image/svg+xml ## ## List of repositories. -## PS: Any repositories listed when repo.group is unset will not be -## displayed under a group heading +## 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 @@ -366,7 +447,7 @@ repo.readme=info/web/about.html # The next repositories will be displayed under the 'extras' heading -repo.group=extras +section=extras repo.url=baz @@ -379,7 +460,7 @@ repo.desc=the wizard of foo # Add some mirrored repositories -repo.group=mirrors +section=mirrors repo.url=git