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