5 kx
10 kx # [cgit-ui.rc(5) Config File](https://csvn.radix.pro/scm-tools/cgit-ui/trunk/doc/cgit-ui.rc.5.md)
5 kx
5 kx **/etc/cgit-ui.rc** – **cGit-ui CGI Script** config file describes the Git™
5 kx repositories that should be displayed on the WEB-client side.
5 kx
5 kx
5 kx ## Table of Contents
5 kx
5 kx * [File Format](#file-format)
5 kx * [Data Types](#data-types)
5 kx * [Reserved Variables](#reserved-variables)
5 kx * [Repository Declaration](#repository-declaration)
5 kx * [Working Example](#working-example)
5 kx * [See Also](#see-also)
5 kx
5 kx
5 kx ## File Format
5 kx
5 kx **/etc/cgit-ui.rc** is a regular text file created by user to present Git repositories. This file
10 kx reads by [**cscmd(8)**](https://csvn.radix.pro/scm-tools/cscm/trunk/doc/cscmd.8.md) daemon and converts to binary
5 kx form for **cGit-ui** CGI script. Binary format allows to minimize the time needed for complete HTTP
5 kx responses.
5 kx
5 kx The configuration file consists of a set of variable or repository declarations also configuration
5 kx file can contains section of repository descriptions. The C/C++ comments are available:
5 kx
5 kx ```dts
5 kx /**************************
5 kx Kernel Git repositories:
5 kx */
5 kx home-page = "https://www.kernel.org/";
5 kx
5 kx repo 'git.git' {
5 kx owner = "Junio C. Hamano";
5 kx title = "The core git plumbing";
5 kx description = "Git – fast, scalable, distributed revision control system.";
5 kx git-root = '/pub/scm/git';
5 kx clone-prefix-readonly = 'git://git.kernel.org/pub/scm/git';
5 kx home-page = "https://git-scm.com/";
5 kx }
5 kx
5 kx section "Other Repositories" {
5 kx repo 'other-repository' {
5 kx . . .
5 kx }
5 kx . . .
5 kx }
5 kx ```
5 kx
5 kx ### Data Types
5 kx
5 kx Configuration file assumes three types of variables.
5 kx
5 kx > **int** – integer constants. Example declaration:
5 kx
5 kx >> ```dts
5 kx >> true = 1;
5 kx >> ```
5 kx
5 kx
5 kx > **string** – string constants. Example declaration:
5 kx
5 kx >> ```dts
5 kx >> name = "Git-scm";
5 kx >> ```
5 kx
5 kx
5 kx > **path** – path constants. Example declaration:
5 kx
5 kx >> ```dts
5 kx >> path = '/etc/cgit-ui.rc';
5 kx >> ```
5 kx
5 kx
5 kx ### Reserved Variables
5 kx
5 kx There is a set of variable names used by **cGit-ui** CGI Script.
5 kx
5 kx
5 kx #### git-root
5 kx
5 kx The name of directory where Git repositories is placed on the filesystem. For example:
5 kx
5 kx ```dts
5 kx git-root = '/pub/scm/git';
5 kx ```
5 kx
5 kx #### repo-root
5 kx
5 kx The name of directory where some repository is placed related to **git-root** directory. For example:
5 kx
5 kx ```dts
5 kx repo-root = 'dm644x';
5 kx ```
5 kx
5 kx
5 kx #### git-utc-offset
5 kx
5 kx The integer or string value of UTC offset on the Git server where repositories are published.
5 kx For example:
5 kx
5 kx ```dts
5 kx git-utc-offset = +0300; /* Europe/Moscow time zone */
5 kx ```
5 kx
5 kx
5 kx #### clone-prefix-readonly
5 kx
5 kx The clone prefix for readonly access to the repository. The value of this variable should
5 kx has **path** type without leadinfg dir-separator. Example declaration:
5 kx
5 kx ```dts
5 kx clone-prefix-readonly = 'git://example.com';
5 kx ```
5 kx
5 kx
5 kx #### clone-prefix
5 kx
5 kx The clone prefix for readwrite access to the repository. The value of this variable should
5 kx has **path** type without leadinfg dir-separator. Example declaration:
5 kx
5 kx ```dts
5 kx clone-prefix = 'git://git@example.com:pub';
5 kx ```
5 kx
5 kx This means the access on behalf **git** system user.
5 kx
5 kx
5 kx #### trunk
5 kx
5 kx The name of the main branch of particular repository. Default value is *'master'*.
5 kx
5 kx Example declarations of main branch name:
5 kx
5 kx ```dts
5 kx trunk = 'master';
5 kx ```
5 kx
5 kx
5 kx #### snapshots
5 kx
5 kx The extension of snapshot tarballs. Default value: *'tar.xz'*. Example declaration:
5 kx
5 kx ```dts
5 kx snapshots = 'tar.xz';
5 kx ```
5 kx
5 kx Currently snapshot variable is not used by **cGit-ui** CGI Script.
5 kx
5 kx
5 kx #### css
5 kx
5 kx The full name of the CSS style sheet relative to the directory where **cGit-ui** CGI Sctipt is installed.
5 kx Example declaration:
5 kx
5 kx ```dts
5 kx css = '/.cgit/css/cgit.css';
5 kx ```
5 kx
5 kx
5 kx #### logo
5 kx
5 kx Url which specifies the source of an image which will be used as a logo (i.e right banner)
5 kx on **cGit-ui** pages. Default value: *'/.cgit/pixmaps/cgit-banner-280x280.png'*. The path to the
5 kx **logo** also should be set relative to the directory where **cGit-ui** CGI Script is installed.
5 kx Example declaration:
5 kx
5 kx ```dts
5 kx logo = '/.cgit/pixmaps/cgit-banner-280x280.png';
5 kx ```
5 kx
5 kx
5 kx #### logo-alt
5 kx
5 kx The string used in HTML as a 'alt' property of the right banner <img> tag.
5 kx Default value: *"Example.org"*. Example declaration:
5 kx
5 kx ```dts
5 kx logo-alt = "Example.org";
5 kx ```
5 kx
5 kx
5 kx #### logo-link
5 kx
5 kx The string used in HTML as a 'href' property of the right banner image link <a> tag.
5 kx Default value: *"https://example.org"*. Example declaration:
5 kx
5 kx ```dts
5 kx logo-link = "https://example.org";
5 kx ```
5 kx
5 kx
5 kx #### main-menu-logo
5 kx
5 kx Url which specifies the source of an image which will be used as a logo of the main menu item
5 kx on **cGit-ui** pages. Default value: *'/.cgit/pixmaps/logo/git-logo-white-256x256.svg'*. The path
5 kx to the *main-menu-logo* also should be set relative to the directory where **cGit-ui** CGI Script
5 kx is installed. Example declaration:
5 kx
5 kx ```dts
5 kx main-menu-logo = '/.cgit/pixmaps/logo/git-logo-white-256x256.svg';
5 kx ```
5 kx
5 kx
5 kx #### favicon-path
5 kx
5 kx The directory name of the *favicon.ico* file without leadind dir-separator.
5 kx Default value: *'/.cgit/pixmaps/favicon'*. Example declaration:
5 kx
5 kx ```dts
5 kx favicon-path = '/.cgit/pixmaps/favicon';
5 kx ```
5 kx
5 kx This directory name used for finding additional images declared in the HTML **header** of all
5 kx **cGit-ui** pages.
5 kx
5 kx
5 kx #### syntax-highlight-css
5 kx
5 kx The base name of the CSS style sheet file used for syntax highlighting.
5 kx Default value: *'_cgit.css'*. Example declaration:
5 kx
5 kx ```dts
5 kx syntax-highlight-css = '_cgit.css';
5 kx ```
5 kx
5 kx **cGit-ui** CGI Script uses [highlight.js](https://highlightjs.org/) installed into
5 kx `/.cgit/.engines/highlight/${hljs-version}/{css,js}` directories where the default
5 kx *_cgit.css* file is palced too.
5 kx
5 kx
5 kx #### header
5 kx
5 kx The content of the file specified with this option will be included verbatim at the top of all pages.
5 kx Default value: *'/.cgit/html/header.html'*.
5 kx
5 kx #### footer
5 kx
5 kx The content of the file specified with this option will be included verbatim at the bottom of all pages.
5 kx Default value: *'/.cgit/html/footer.html'*. Examle of the **header** and the **footer** declarations:
5 kx
5 kx ```dts
5 kx header = '/.cgit/html/header.html';
5 kx footer = '/.cgit/html/footer.html';
5 kx ```
5 kx
5 kx The **header** and the **footer** files used as template where **cGit-ui** CGI Script substitute
5 kx placeholders such as `${variable-name}` by their values. For example the `${css}` placeholder
5 kx will be replaced by the value of **css** variable declared in the **/etc/cgit-ui.rc** config file.
5 kx
5 kx
5 kx #### page-size
5 kx
5 kx The **string** or **int** variable which set the length of the repositories list or logs that shown
5 kx in one page by the **cGit-ui** CGI Script. Default value: 200. Example declaration:
5 kx
5 kx ```dts
5 kx page-size = 50; /* 10 ... 200 may be string or integer. Default value is page-size = 200 */
5 kx ```
5 kx
5 kx #### owner
5 kx
5 kx The **string** variable used in the HTML header of all **cGit-ui** pages and also in the *Owner* colon
5 kx of the repository list. Default value: *"Andrey V.Kosteltsev"*.
5 kx
5 kx #### author
5 kx
5 kx The **string** variable used in the HTML header of all **cGit-ui** pages. Default value: *"Andrey V.Kosteltsev"*.
5 kx Example declarations of the **owner** and the **author** variables:
5 kx
5 kx ```dts
5 kx owner = "John Smith";
5 kx author = "John Smith";
5 kx ```
5 kx
5 kx
5 kx #### title
5 kx
5 kx The **string** variable used in the HTML header of all **cGit-ui** pages as a page title.
5 kx Default value: *"Git Repositories"*. Example declaration:
5 kx
5 kx ```dts
5 kx title = "Example.org Git Repositories";
5 kx ```
5 kx
5 kx
5 kx #### description
5 kx
5 kx The **string** variable used in the HTML header of all **cGit-ui** pages as a page description.
5 kx Default value: *"Git repositories hosted at Solar System, Earth"*.
5 kx Example declaration:
5 kx
5 kx ```dts
5 kx description = "Git repositories hosted at example.org (St.-Petersburg)";
5 kx ```
5 kx
5 kx For a long description the value of this **string** variable can be defined by following way:
5 kx
5 kx ```dts
5 kx description = "Git repositories
5 kx hosted at example.org
5 kx (St.-Petersburg)";
5 kx ```
5 kx
5 kx
5 kx #### keywords
5 kx
5 kx The **string** variable contains space separated keywords used in the HTML header of all **cGit-ui**
5 kx pages as a page keywords. Default value: *"cGit repositories"*. Example declaration:
5 kx
5 kx ```dts
5 kx keywords = "cGit UI CGI Git Repositories scm";
5 kx ```
5 kx
5 kx
5 kx #### copyright-notice
5 kx
5 kx The **string** variable used in the HTML footer of all **cGit-ui** pages as a *Copyright Notice*.
5 kx Default value: *"By using any website materials you agree to indicate source."*.
5 kx Example declaration:
5 kx
5 kx ```dts
5 kx copyright-notice = "By using any materials you agree with ...";
5 kx ```
5 kx
5 kx
5 kx #### copyright
5 kx
5 kx The **string** variable used in the HTML footer of all **cGit-ui** pages as a *Copyright*.
5 kx Default value: *"© 2022 Andrey V.Kosteltsev. All Rights Reserved."*.
5 kx Example declaration:
5 kx
5 kx ```dts
5 kx copyright = "© John Smith (explorer), 1580 - 1631.";
5 kx ```
5 kx
5 kx
5 kx #### home-page
5 kx
5 kx The URL of the home page of the project. Default value: *"https://example.org"*.
5 kx Example declaration:
5 kx
5 kx ```dts
5 kx home-page = "https://main-site-of-the-project.org";
5 kx ```
5 kx
5 kx
5 kx ### Analytics variables:
5 kx
5 kx
5 kx #### analytic-links
5 kx
5 kx The path to the file which contains meta tags with site ownership verificaton codes for engines such as *Google Search Console* or
5 kx *Yandex Webmaster*. **cGit-ui** CGI Script reads the file **analytic-links** in RAW format and includes it into <HEAD> tag of each HTML page.
5 kx Example declaration:
5 kx
5 kx ```dts
5 kx analytic-links = '/analytics/links';
5 kx ```
5 kx
5 kx Where the file */analytics/links* may contains HTML tags like follow:
5 kx
5 kx ```html
5 kx <meta name="google-site-verification" content="..." />
5 kx ```
5 kx
5 kx The file name should be defined relative of the path where **cGit-ui** CGI Script is installed. For example, if **cGit-ui** CGI Script installed
5 kx into */srv/www/htdocs/cgit* directory and file name declared as */analytics/links* then **cGit-ui** CGI Script will try to read the
5 kx file */srv/www/htdocs/cgit/analytics/links*.
5 kx
5 kx
5 kx #### analytic-scripts
5 kx
5 kx The path to the file which contains *JavaScripts* for engines such as *Google Search Console* or
5 kx *Yandex Webmaster*. **cGit-ui** CGI Script reads the file **analytic-scripts** in RAW format and includes it at the end of <HEAD> tag before
5 kx </HEAD> entry of each HTML page. Example declaration:
5 kx
5 kx ```dts
5 kx analytic-scripts = '/analytics/scripts';
5 kx ```
5 kx
5 kx Where the file */analytics/scripts* may contains code like follow:
5 kx
5 kx ```html
5 kx <!-- Global site tag (gtag.js) - Google Analytics -->
5 kx <script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
5 kx <script>
5 kx window.dataLayer = window.dataLayer || [];
5 kx function gtag(){dataLayer.push(arguments);}
5 kx gtag('js', new Date());
5 kx
5 kx gtag('config', 'G-XXXXXXXXXX');
5 kx </script>
5 kx ```
5 kx
5 kx Please note that the *<script>* tags should be present in the */analytics/scripts* because **cGit-ui** CGI Script reads this file
5 kx in RAW format and includes it as is.
5 kx
5 kx The variables **analytic-links** and **analytic-scripts** should be declared on the global level of the **/etc/cgit-ui.rc**
5 kx configuration file and cannot be overriden in a repository declaration.
5 kx
5 kx
5 kx ### Donation variables:
5 kx
5 kx The **cGit-ui** CGI Script provides the ability to create a custom donation dialogue. To do this, you need to create a set of three files:
5 kx **CSS**, **HTML**, and **JavaScript** file for automation. You can add a donation dialogue for each repository separately, as well as for the
5 kx entire list of repositories. To enable donation dialogue you have to set the value of **donate** variable to **donate = 1**:
5 kx
5 kx
5 kx #### donate
5 kx
5 kx The integer variable used to enable or disable donation dialogue. Example declaration:
5 kx
5 kx ```dts
5 kx donate = 1;
5 kx ```
5 kx
5 kx #### donate-css
5 kx
5 kx The name of file contains the stylesheet for donation modal dialogue. Example declaration:
5 kx
5 kx ```dts
5 kx donate-css = '/donations/donate.css';
5 kx ```
5 kx
5 kx #### donate-html
5 kx
5 kx The name of file contains the HTML code of donation modal dialogue. Example declaration:
5 kx
5 kx ```dts
5 kx donate-html = '/donations/donate.html';
5 kx ```
5 kx
5 kx #### donate-js
5 kx
5 kx The name of file contains the javascript code for donation modal dialogue automation. Example declaration:
5 kx
5 kx ```dts
5 kx donate-js = '/donations/donate.js';
5 kx ```
5 kx
5 kx **cGit-ui** CGI Script includes these files at end of <BODY> tag just before the closing </BODY> tag. Unlike the others,
5 kx the **donate-html** file should be no more than 8192 bytes in size due to the fact that this file is a template
5 kx and the values of the following two variables are substituted into its body using placeholders *${donate-header}*
5 kx and *${donate-purpose}*:
5 kx
5 kx
5 kx #### donate-header
5 kx
5 kx The title of the donation modal dialogue defined in the **donate-html** file. Example declaration:
5 kx
5 kx ```dts
5 kx donate-header = "Donations";
5 kx ```
5 kx
5 kx #### donate-purpose
5 kx
5 kx The donation purpose used as value of <input value="..."> tag property in payment form of systems such as **PayPal** or **Yandex.Money**.
5 kx Also this value can be used as a header of modal dialogue content. Example declaration:
5 kx
5 kx ```dts
5 kx donate-purpose = "Support for our projects";
5 kx ```
5 kx
5 kx Donation dialogue can be defined for each repository separately or defined on global level. In the last case
5 kx the dialogue header and payment purpose may be overriden in the body of a repository declaration like follow:
5 kx
5 kx ```dts
5 kx true = 1;
5 kx false = 0;
5 kx
5 kx donate = true;
5 kx donate-css = '/donations/donate.css';
5 kx donate-html = '/donations/donate.html';
5 kx donate-js = '/donations/donate.js';
5 kx donate-header = "Donation";
5 kx donate-purpose = "Support our activities";
5 kx
5 kx section "Tools" {
5 kx repo 'repo-path' {
5 kx . . .
5 kx donate-header = "Project Donation";
5 kx donate-purpose = "Support our Project";
5 kx . . .
5 kx }
5 kx }
5 kx ```
5 kx
5 kx To show the modal dialogue in javascript code **donate-js** the selector **'a.donate'** should be used. For examle, like this:
5 kx
5 kx ```php
5 kx var show = document.querySelector( "a.donate" );
5 kx
5 kx /**************
5 kx Open Dialog:
5 kx */
5 kx show.onclick = function() {
5 kx dialog.style.display = "block";
5 kx }
5 kx ```
5 kx
5 kx Where the variable *dialog* points to modal dialogue defined in the **donate-html** file.
5 kx
5 kx
5 kx
5 kx ### Repository Declaration
5 kx
5 kx The **/etc/cgit-ui.rc** config file should contains at least one repository declaration to be shown
5 kx by the **cGit-ui** CGI Script. When all expected variables declared in the global section
5 kx the config file the repository declaration can be very simple:
5 kx
5 kx ```dts
5 kx repo 'tools' {
5 kx owner = "John Smith";
5 kx description = "John Smith's tools source code repository.";
5 kx }
5 kx ```
5 kx
5 kx The list of repositories can be splitted in several sections. The section has a name and can
5 kx contains repository declarations only.
5 kx
5 kx ```dts
5 kx section "John Smith sources" {
5 kx repo 'tools' {
5 kx owner = "John Smith";
5 kx description = "John Smith's tools source code repository.";
5 kx }
5 kx repo 'examples' {
5 kx owner = "John Smith";
5 kx description = "John Smith's examples source code.";
5 kx }
5 kx }
5 kx ```
5 kx
5 kx Please note, repositories, unlike sections, do not have a name, but have a **path** to repository.
5 kx So if your repositories in the file system are stored in the `/var/scm/git` directory, and the
5 kx `tools` repository is located in the `/var/scm/git/tools` directory, then the path to the repository
5 kx is set relative to the `/var/scm/git` directory as follows:
5 kx
5 kx ```dts
5 kx repo 'tools' {
5 kx owner = "John Smith";
5 kx description = "John Smith's tools source code repository.";
5 kx }
5 kx ```
5 kx
5 kx
5 kx ## Working Example
5 kx
5 kx As an example, we will give a working configuration file in which the
5 kx [**pkgtools.git**](https://cgit.radix.pro/pkgtools.git/trunk/) repository is presented.
5 kx
5 kx ```dts
5 kx git-utc-offset = +0300;
5 kx
5 kx clone-prefix-readonly = 'git://radix.pro';
5 kx clone-prefix = 'git://git@radix.pro:pub';
5 kx
5 kx trunk = 'master';
5 kx
5 kx snapshots = 'tar.xz';
5 kx
5 kx css = '/.cgit/css/cgit.css';
5 kx logo = '/.cgit/pixmaps/cgit-banner-280x280.png';
5 kx logo-alt = "Radix.pro";
5 kx logo-link = "https://radix.pro";
5 kx main-menu-logo = '/.cgit/pixmaps/logo/git-logo-white-256x256.svg';
5 kx favicon-path = '/.cgit/pixmaps/favicon';
5 kx syntax-highlight-css = '_cgit.css';
5 kx header = '/.cgit/html/header.html';
5 kx footer = '/.cgit/html/footer.html';
5 kx page-size = 200;
5 kx
5 kx owner = "Andrey V.Kosteltsev";
5 kx author = "Andrey V.Kosteltsev";
5 kx title = "Radix.pro Git Repositories";
5 kx description = "Git repositories hosted at radix.pro (St.-Petersburg)";
5 kx keywords = "cGit repositories cgit-ui web web-ui user interface Git";
5 kx copyright = "© Andrey V. Kosteltsev, 2019 – 2022.";
5 kx copyright-notice = "Where any material of this site is being reproduced, published or issued to others the reference to the source is obligatory.";
5 kx
5 kx home-page = "https://radix.pro/";
5 kx
5 kx section "Tools" {
5 kx repo 'pkgtools.git' {
5 kx owner = "Andrey V.Kosteltsev";
5 kx title = "Package Tools Utilities";
5 kx description = "Pkgtools – is a set of utilities to create, install, remove and update packages";
5 kx home-page = "https://radix.pro/";
5 kx git-root = '/u3/scm/git';
5 kx clone-prefix-readonly = 'git://git@radix.pro:git';
5 kx clone-prefix = 'git://git@radix.pro:git';
5 kx }
5 kx }
5 kx
5 kx ```
5 kx
5 kx
5 kx ## See Also
5 kx
10 kx > [**README**](https://csvn.radix.pro/scm-tools/cgit-ui/trunk/README.md),
10 kx > [**cscmd(8)**](https://csvn.radix.pro/scm-tools/cscm/trunk/doc/cscmd.8.md)
5 kx
cGit-UI for Git Repositories
cGit-UI – is a web interface for Git Repositories. cGit CGI script is writen in C and therefore it's fast enough
12 Commits
0 Branches
1 Tag