filters: document environment variables in filter scripts

Signed-off-by: Ferry Huberts <ferry.huberts@pelagic.nl>
Signed-off-by: Lars Hjemli <hjemli@gmail.com>

diff --git a/cgitrc.5.txt b/cgitrc.5.txt
index c3698a643dc65a7d7cee43d3da780bbe9e844c2c..60539d7ecf947ba7c2aee9d760a8095fef099795 100644 (file)
--- 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
@@ -81,6 +81,7 @@ commit-filter::
        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.
@@ -316,7 +317,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"
@@ -349,7 +350,7 @@ 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.
@@ -357,7 +358,7 @@ repo.clone-url::
 
 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
@@ -428,7 +429,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
@@ -448,6 +449,42 @@ 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        ( = repo.url       setting )
+- CGIT_REPO_NAME       ( = repo.name      setting )
+- CGIT_REPO_PATH       ( = repo.path      setting )
+- CGIT_REPO_OWNER      ( = repo.owner     setting )
+- CGIT_REPO_DEFBRANCH  ( = repo.defbranch setting )
+- CGIT_REPO_SECTION    ( = section        setting )
+- CGIT_REPO_CLONE_URL  ( = repo.clone-url setting )
+
+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.
+
+Note that under normal circumstance all these environment variables are
+defined. If however the total size of the defined settings exceed the
+allocated buffer within cgit then only the environment variables that fit
+in the allocated buffer are handed to the filter.
+
+
 EXAMPLE CGITRC FILE
 -------------------
 

diff --git a/filters/commit-links.sh b/filters/commit-links.sh
index 110c6091f37aeaa48a2fc0f1fbd119b989ca5564..d2cd2b33f3ff698ee80ccb1656272340d2d36ff3 100755 (executable)
--- a/filters/commit-links.sh
+++ b/filters/commit-links.sh
@@ -3,6 +3,17 @@
 #
 # To use this script, refer to this file with either the commit-filter or the
 # repo.commit-filter options in cgitrc.
+#
+# The following environment variables can be used to retrieve the configuration
+# of the repository for which this script is called:
+# CGIT_REPO_URL        ( = repo.url       setting )
+# CGIT_REPO_NAME       ( = repo.name      setting )
+# CGIT_REPO_PATH       ( = repo.path      setting )
+# CGIT_REPO_OWNER      ( = repo.owner     setting )
+# CGIT_REPO_DEFBRANCH  ( = repo.defbranch setting )
+# CGIT_REPO_SECTION    ( = section        setting )
+# CGIT_REPO_CLONE_URL  ( = repo.clone-url setting )
+#
 
 # This expression generates links to commits referenced by their SHA1.
 regex=$regex'

diff --git a/filters/syntax-highlighting.sh b/filters/syntax-highlighting.sh
index 6b1c576404f886b9368b6147cf1e83cae819f274..6283ce92efc62e9cf63d2bd20486af43bec7b489 100755 (executable)
--- a/filters/syntax-highlighting.sh
+++ b/filters/syntax-highlighting.sh
@@ -23,6 +23,17 @@
 # table.blob .kwb  { color:#830000; }
 # table.blob .kwc  { color:#000000; font-weight:bold; }
 # table.blob .kwd  { color:#010181; }
+#
+# The following environment variables can be used to retrieve the configuration
+# of the repository for which this script is called:
+# CGIT_REPO_URL        ( = repo.url       setting )
+# CGIT_REPO_NAME       ( = repo.name      setting )
+# CGIT_REPO_PATH       ( = repo.path      setting )
+# CGIT_REPO_OWNER      ( = repo.owner     setting )
+# CGIT_REPO_DEFBRANCH  ( = repo.defbranch setting )
+# CGIT_REPO_SECTION    ( = section        setting )
+# CGIT_REPO_CLONE_URL  ( = repo.clone-url setting )
+#
 
 # store filename and extension in local vars
 BASENAME="$1"