cgit-ui.rc(5) Config File
/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
/etc/cgit-ui.rc is a regular text file created by user to present Git repositories. This file reads by cscmd(8) 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:
/**************************
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:
true = 1;
string – string constants. Example declaration:
name = "Git-scm";
path – path constants. Example declaration:
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:
git-root = '/pub/scm/git';
repo-root
The name of directory where some repository is placed related to git-root directory. For example:
repo-root = 'dm644x';
git-utc-offset
The integer or string value of UTC offset on the Git server where repositories are published. For example:
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:
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:
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:
trunk = 'master';
snapshots
The extension of snapshot tarballs. Default value: 'tar.xz'. Example declaration:
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:
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:
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:
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:
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:
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:
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:
syntax-highlight-css = '_cgit.css';
cGit-ui CGI Script uses highlight.js 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:
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:
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:
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:
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:
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:
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:
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:
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:
copyright = "© John Smith (explorer), 1580 - 1631.";
home-page
The URL of the home page of the project. Default value: "https://example.org". Example declaration:
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:
analytic-links = '/analytics/links';
Where the file /analytics/links may contains HTML tags like follow:
<meta name="google-site-verification" content="..." />
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:
analytic-scripts = '/analytics/scripts';
Where the file /analytics/scripts may contains code like follow:
<!-- Global site tag (gtag.js) - Google Analytics -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-XXXXXXXXXX"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-XXXXXXXXXX');
</script>
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:
donate = 1;
donate-css
The name of file contains the stylesheet for donation modal dialogue. Example declaration:
donate-css = '/donations/donate.css';
donate-html
The name of file contains the HTML code of donation modal dialogue. Example declaration:
donate-html = '/donations/donate.html';
donate-js
The name of file contains the javascript code for donation modal dialogue automation. Example declaration:
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:
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:
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:
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:
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:
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.
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:
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 repository is presented.
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';
}
}