X-Git-Url: https://gitweb.ps.run/ps-cgit/blobdiff_plain/f35db1cd2b75aac6952aa07713e44ca01fd89727..fbd254d54e28e002a0d56b81c192156599df1e6b:/cgitrc.5.txt diff --git a/cgitrc.5.txt b/cgitrc.5.txt index 2efd6aa..26c4bfc 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. @@ -25,7 +42,7 @@ agefile:: cache-root:: Path used to store the cgit cache entries. Default value: - "/var/cache/cgit". + "/var/cache/cgit". See also: "MACRO EXPANSION". cache-dynamic-ttl:: Number which specifies the time-to-live, in minutes, for the cached @@ -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). @@ -69,7 +90,21 @@ 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-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-gitweb-owner:: + If set to "1" and scan-path is enabled, we first check each repository + for the git config value "gitweb.owner" to determine the owner. + Default value: "1". See also: scan-path. + 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", @@ -85,6 +120,21 @@ enable-log-linecount:: and removed lines for each commit on the repository log page. Default value: "0". +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-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 @@ -105,7 +155,7 @@ header:: include:: Name of a configfile to include before the rest of the current config- - file is parsed. Default value: none. + file is parsed. Default value: none. See also: "MACRO EXPANSION". index-header:: The content of the file specified with this option will be included @@ -125,13 +175,17 @@ 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 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-commit-count:: Specifies the number of entries to list per page in "log" view. Default value: "50". @@ -148,11 +202,19 @@ max-repodesc-length:: Specifies the maximum number of repo description characters to display on the repository index page. Default value: "80". +max-blob-size:: + Specifies the maximum size of a blob to display HTML for in KBytes. + Default value: "0" (limit disabled). + max-stats:: Set the default maximum statistics period. Valid values are "week", "month", "quarter" and "year". If unspecified, statistics are disabled. Default value: none. See also: "repo.max-stats". +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 @@ -164,18 +226,37 @@ 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". +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". Default + value: none. + +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. 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". 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: @@ -194,15 +275,44 @@ 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-from-path:: + A number which, if specified before 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 (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", "tar.xz" and "zip". Default value: + none. source-filter:: Specifies a command which will be invoked to format plaintext blobs @@ -224,6 +334,13 @@ 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 come + before '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 @@ -234,10 +351,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 @@ -246,6 +371,10 @@ repo.defbranch:: repo.desc:: The value to show as repository description. 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-log-filecount:: A flag which can be used to disable the global setting `enable-log-filecount'. Default value: none. @@ -254,6 +383,29 @@ 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-subject-links:: + A flag which can be used to override the global setting + `enable-subject-links'. Default value: none. + +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 path and SHA1 of the submodule commit. 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. Default @@ -272,17 +424,60 @@ repo.path:: repo.readme:: A path (relative to ) which specifies a file to include - verbatim as the "About" page for this repo. Default value: none. + 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" Default value: . 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". + + +MACRO EXPANSION +--------------- +The following cgitrc options supports a simple macro expansion feature, +where tokens prefixed with "$" are replaced with the value of a similary +named environment variable: + +- cache-root +- include +- project-list +- scan-path + +Macro expansion will also happen on the content of $CGIT_CONFIG, if +defined. + +One usage of this feature is virtual hosting, which in its simplest form +can be accomplished by adding the following line to /etc/cgitrc: + + include=/etc/cgitrc.d/$HTTP_HOST + + EXAMPLE CGITRC FILE ------------------- @@ -292,7 +487,7 @@ cache-size=1000 # Specify some default clone prefixes -clone-prefix=git://foobar.com ssh://foobar.com/pub/git http://foobar.com/git +clone-prefix=git://example.com ssh://example.com/pub/git http://example.com/git # Specify the css url css=/css/cgit.css @@ -302,6 +497,10 @@ css=/css/cgit.css enable-index-links=1 +# Enable ASCII art commit history graph on the log pages +enable-commit-graph=1 + + # Show number of affected files per commit on the log pages enable-log-filecount=1 @@ -323,14 +522,14 @@ max-stats=quarter # Set the title and heading of the repository index page -root-title=foobar.com git repositories +root-title=example.com git repositories # Set a subheading for the repository index page root-desc=tracking the foobar development -# Include some more info about foobar.com on the index page +# Include some more info about example.com on the index page root-readme=/var/www/htdocs/about.html @@ -338,10 +537,23 @@ root-readme=/var/www/htdocs/about.html snapshots=tar.gz tar.bz2 zip +## +## List of common mimetypes +## + +mimetype.gif=image/gif +mimetype.html=text/html +mimetype.jpg=image/jpeg +mimetype.jpeg=image/jpeg +mimetype.pdf=application/pdf +mimetype.png=image/png +mimetype.svg=image/svg+xml + + ## ## 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 @@ -351,19 +563,19 @@ snapshots=tar.gz tar.bz2 zip repo.url=foo repo.path=/pub/git/foo.git repo.desc=the master foo repository -repo.owner=fooman@foobar.com +repo.owner=fooman@example.com repo.readme=info/web/about.html repo.url=bar repo.path=/pub/git/bar.git repo.desc=the bars for your foo -repo.owner=barman@foobar.com +repo.owner=barman@example.com repo.readme=info/web/about.html # The next repositories will be displayed under the 'extras' heading -repo.group=extras +section=extras repo.url=baz @@ -376,7 +588,7 @@ repo.desc=the wizard of foo # Add some mirrored repositories -repo.group=mirrors +section=mirrors repo.url=git @@ -415,3 +627,4 @@ will generate the following html element: AUTHOR ------ Lars Hjemli +Jason A. Donenfeld