+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 invalid,
+ 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.
+
+ Please see `filters/simple-authentication.lua` for a clear example
+ script that may be modified.
+
+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.
+
+owner filter::
+ This filter is given no arguments. The owner text is available on
+ standard input and the filter is expected to write to standard
+ output. The output is included in the Owner column.
+
+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.
+
+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 during request processing, and support
+the environment 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.
+
+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.
+
+
git.ckatri.com / cgit.git / blobdiff