about summary refs log tree commit diff
path: root/cgitrc.5.txt
diff options
context:
space:
mode:
Diffstat (limited to 'cgitrc.5.txt')
-rw-r--r--cgitrc.5.txt67
1 files changed, 59 insertions, 8 deletions
diff --git a/cgitrc.5.txt b/cgitrc.5.txt
index 26c4bfc..4721c1e 100644
--- a/cgitrc.5.txt
+++ b/cgitrc.5.txt
@@ -31,7 +31,7 @@ about-filter::
 	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.
+	none. See also: "FILTER API".
 
 agefile::
 	Specifies a path, relative to each repository path, which can be used
@@ -76,11 +76,17 @@ clone-prefix::
 	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".
 
 css::
 	Url which specifies the css document to include in all cgit pages.
@@ -105,6 +111,11 @@ enable-gitweb-owner::
 	for the git config value "gitweb.owner" to determine the owner.
 	Default value: "1". See also: scan-path.
 
+enable-http-clone::
+	If set to "1", cgit will act as an dumb HTTP endpoint for git clones.
+	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",
@@ -320,7 +331,7 @@ source-filter::
 	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.
+	none. See also: "FILTER API".
 
 summary-branches::
 	Specifies the number of branches to display in the repository "summary"
@@ -353,15 +364,15 @@ REPOSITORY SETTINGS
 -------------------
 repo.about-filter::
 	Override the default about-filter. Default value: none. See also:
-	"enable-filter-overrides".
+	"enable-filter-overrides". See also: "FILTER API".
 
 repo.clone-url::
 	A list of space-separated urls which can be used to clone this repo.
-	Default value: none.
+	Default value: none. See also: "MACRO EXPANSION".
 
 repo.commit-filter::
 	Override the default commit-filter. Default value: none. See also:
-	"enable-filter-overrides".
+	"enable-filter-overrides". See also: "FILTER API".
 
 repo.defbranch::
 	The name of the default branch for this repository. If no such branch
@@ -438,7 +449,7 @@ repo.section::
 
 repo.source-filter::
 	Override the default source-filter. Default value: none. See also:
-	"enable-filter-overrides".
+	"enable-filter-overrides". See also: "FILTER API".
 
 repo.url::
 	The relative url used to access the repository. This must be the first
@@ -458,6 +469,40 @@ Note: the "repo." prefix is dropped from the option names in repo-specific
 config files, e.g. "repo.desc" becomes "desc".
 
 
+FILTER API
+----------
+about filter::
+	This filter is given no arguments. The about text that is to be
+	filtered is available on standard input and the filtered text is
+	expected on standard output.
+
+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.
+
+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.
+
+Also, 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 an empty string.
+
+
 MACRO EXPANSION
 ---------------
 The following cgitrc options supports a simple macro expansion feature,
@@ -477,6 +522,12 @@ can be accomplished by adding the following line to /etc/cgitrc:
 
 	include=/etc/cgitrc.d/$HTTP_HOST
 
+The following options are expanded during request processing, and support
+the environment variables defined in "FILTER API":
+
+- clone-url
+- repo.clone-url
+
 
 EXAMPLE CGITRC FILE
 -------------------
@@ -486,8 +537,8 @@ EXAMPLE CGITRC FILE
 cache-size=1000
 
 
-# Specify some default clone prefixes
-clone-prefix=git://example.com ssh://example.com/pub/git http://example.com/git
+# Specify some default clone urls using macro expansion
+clone-url=git://foo.org/$CGIT_REPO_URL git@foo.org:$CGIT_REPO_URL
 
 # Specify the css url
 css=/css/cgit.css