5 kx .\"
5 kx .TH "CGIT-UI.RC" 5 "2022-02-19" "cGit-ui CGI script" "cgit-ui.rc"
5 kx
5 kx .SH "NAME"
5 kx \fB/etc/cgit-ui.rc\fR \- cGit-ui CGI script config file
5 kx
5 kx .SH "DESCRIPTION"
5 kx \fB/etc/cgit-ui.rc\fR file describes Git repositories which should be shown by \fBcGit-ui\fR CGI script.
5 kx
5 kx .SH "FILE FORMAT"
5 kx \fB/etc/cgit-ui.rc\fR is regular text file created by user to present Git repositories. This file reads by \fBcscmd\fR daemon
5 kx and converts to binary form for \fBcGit-ui\fR CGI script. Binary format allows to minimize the time needed for complete HTTP responses.
5 kx .PP
5 kx The configuration file consists of a set of variable or repository declarations also configuration file can contains section
5 kx of repository descriptions. The C/C++ comments are available:
5 kx .PP
5 kx .in +4n
5 kx .EX
5 kx \fI
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 \fR
5 kx .EE
5 kx .in
5 kx
5 kx .SH "DATA TYPES"
5 kx Configuration file assumes three types of variables.
5 kx
5 kx .PP
5 kx \fBint\fR \- integer constants. Example declaration:
5 kx .PP
5 kx .in +4n
5 kx .EX
5 kx \fItrue = 1;\fR
5 kx .EE
5 kx .in
5 kx
5 kx .PP
5 kx \fBstring\fR \- string constants. Example declaration:
5 kx .PP
5 kx .in +4n
5 kx .EX
5 kx \fIname = "Git-scm";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .PP
5 kx \fBpath\fR \- path constants. Example declaration:
5 kx .PP
5 kx .in +4n
5 kx .EX
5 kx \fIpath = '/etc/cgit-ui.rc';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .SH "RESERVED VARIABLES"
5 kx There is a set of variable names used by \fBcGit-ui\fR CGI Script.
5 kx
5 kx .TP 4
5 kx \fBgit-root\fR
5 kx The name of directory where Git repositories is placed on the filesystem. For example:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIgit-root = '/pub/scm/git';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBrepo-root\fR
5 kx The name of directory where some repository is placed related to \fBgit-root\fR directory. For example:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIrepo-root = 'dm644x';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBclone-prefix-readonly\fR
5 kx The clone prefix for readonly access to the repository. The value of this variable should has \fBpath\fR type
5 kx without leadinfg dir-separator. Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIclone-prefix-readonly = 'git://example.com';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBclone-prefix\fR
5 kx The clone prefix for readwrite access to the repository. The value of this variable should has \fBpath\fR type
5 kx without leadinfg dir-separator. Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIclone-prefix = 'git://git@example.com:pub';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx This means the access on behalf \fIgit\fR system user.
5 kx .RE
5 kx
5 kx .TP 4
5 kx \fBtrunk\fR
5 kx The name of the main branch of particular repository. Default value is \fImaster\fR.
5 kx .RS 4
5 kx Example declarations of main branch name:
5 kx .RE
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fItrunk = 'master';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBsnapshots\fR
5 kx The extension of snapshot tarballs. Default value: \fI'tar.xz'\fR. Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIsnapshots = 'tar.xz';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx Currently snapshot variable is not used by \fBcGit-ui\fR CGI Script.
5 kx .RE
5 kx
5 kx .TP 4
5 kx \fBcss\fR
5 kx .RS 4
5 kx The full name of the CSS style sheet relative to the directory where \fBcGit-ui\fR CGI Sctipt is installed.
5 kx Example declaration:
5 kx .RE
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIcss = '/.cgit/css/cgit.css';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBlogo\fR
5 kx Url which specifies the source of an image which will be used as a logo (i.e right banner) on \fBcGit-ui\fR pages.
5 kx Default value: \fI'/.cgit/pixmaps/cgit-banner-280x280.png'\fR. The path to the \fBlogo\fR also should be set
5 kx relative to the directory where \fBcGit-ui\fR CGI Script is installed. Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIlogo = '/.cgit/pixmaps/cgit-banner-280x280.png';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBlogo-alt\fR
5 kx The string used in HTML as a 'alt' property of the right banner <img> tag. Default value: \fI"Example.org"\fR.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIlogo-alt = "Example.org";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBlogo-link\fR
5 kx The string used in HTML as a 'href' property of the right banner image link <a> tag. Default value: \fI"https://example.org"\fR.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIlogo-link = "https://example.org";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBmain-menu-logo\fR
5 kx Url which specifies the source of an image which will be used as a logo of the main menu item on \fBcGit-ui\fR pages.
5 kx Default value: \fI'/.cgit/pixmaps/logo/git-logo-white-256x256.svg'\fR. The path to the \fBmain-menu-logo\fR also should be set
5 kx relative to the directory where \fBcGit-ui\fR CGI Script is installed. Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fImain-menu-logo = '/.cgit/pixmaps/logo/git-logo-white-256x256.svg';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBfavicon-path\fR
5 kx The directory name of the 'favicon.ico' file without leadind dir-separator.
5 kx Default value: \fI'/.cgit/pixmaps/favicon'\fR. Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIfavicon-path = '/.cgit/pixmaps/favicon';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx This directory name used for finding additional images declared in the HTML \fBheader\fR of all \fBcGit-ui\fR pages.
5 kx .RE
5 kx
5 kx .TP 4
5 kx \fBsyntax-highlight-css\fR
5 kx The base name of the CSS style sheet file used for syntax highlighting.
5 kx Default value: \fI'_cgit.css'\fR. Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIsyntax-highlight-css = '_cgit.css';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx \fBcGit-ui\fR CGI Script uses highlight.js
5 kx .UR https://\:highlightjs.org\:/
5 kx .UE
5 kx installed into \fI'/.cgit/.engines/highlight/${hljs-version}/{css,js}'\fR directories
5 kx where the default \fI'_cgit.css'\fR file is palced too.
5 kx .RE
5 kx
5 kx .TP 4
5 kx \fBheader\fR
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: \fI'/.cgit/html/header.html'\fR.
5 kx .TP 4
5 kx \fBfooter\fR
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: \fI'/.cgit/html/footer.html'\fR. Examle of the \fBheader\fR and the \fBfooter\fR declarations:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIheader = '/.cgit/html/header.html';\fR
5 kx \fIfooter = '/.cgit/html/footer.html';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx The \fBheader\fR and the \fBfooter\fR files used as template where \fBcGit-ui\fR CGI Script substitute placeholders
5 kx such as \fI${variable-name}\fR by their values. For example the ${css} placeholder will be replaced by the value
5 kx of \fIcss\fR variable declared in the \fB/etc/cgit-ui.rc\fR config file.
5 kx .RE
5 kx
5 kx .TP 4
5 kx \fBpage-size\fR
5 kx The \fBstring\fR or \fBint\fR variable which set the length of the repositories list or logs shown in one page by the \fBcGit-ui\fR CGI Script.
5 kx Default value: 200. Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIpage-size = 50; /* 10 ... 200 may be string or integer. Default value is page-size = 200 */\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBowner\fR
5 kx The \fBstring\fR variable used in the HTML header of all \fBcGit-ui\fR pages and also in the \fIOwner\fR colon of the repository list.
5 kx Default value: \fI"Andrey V.Kosteltsev"\fR.
5 kx .TP 4
5 kx \fBauthor\fR
5 kx The \fBstring\fR variable used in the HTML header of all \fBcGit-ui\fR pages. Default value: \fI"Andrey V.Kosteltsev"\fR.
5 kx Example declarations of the \fBowner\fR and the \fBauthor\fR variables:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIowner = "John Smith";\fR
5 kx \fIauthor = "John Smith";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBtitle\fR
5 kx The \fBstring\fR variable used in the HTML header of all \fBcGit-ui\fR pages as a page title. Default value: \fI"Git Repositories"\fR.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fItitle = "Example.org Git Repositories";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBdescription\fR
5 kx The \fBstring\fR variable used in the HTML header of all \fBcGit-ui\fR pages as a page description.
5 kx Default value: \fI"Git repositories hosted at Solar System, Earth"\fR.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIdescription = "Git repositories hosted at example.org (St.-Petersburg)";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx For a long description the value of this \fBstring\fR variable can be defined by following way:
5 kx .RE
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIdescription = "Git repositories\fR
5 kx \fI hosted at example.org\fR
5 kx \fI (St.-Petersburg)";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBkeywords\fR
5 kx The \fBstring\fR variable contains space separated keywords used in the HTML header of all \fBcGit-ui\fR pages as a page keywords.
5 kx Default value: \fI"cGit repositories"\fR.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIkeywords = "cGit UI CGI Git Repositories scm";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBcopyright-notice\fR
5 kx The \fBstring\fR variable used in the HTML footer of all \fBcGit-ui\fR pages as a Copyright Notice.
5 kx Default value: \fI"By using any website materials you agree to indicate source."\fR.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIcopyright-notice = "By using any materials you agree with ...";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBcopyright\fR
5 kx The \fBstring\fR variable used in the HTML footer of all \fBcGit-ui\fR pages as a Copyright.
5 kx Default value: \fI"© 2022 Andrey V.Kosteltsev. All Rights Reserved."\fR.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIcopyright = "© John Smith (explorer), 1580 - 1631.";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBhome-page\fR
5 kx The URL of the home page of the project.
5 kx Default value: \fI"https://example.org"\fR.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIhome-page = "https://main-site-of-the-project.org";\fR
5 kx .EE
5 kx .in
5 kx
5 kx Analytics variables:
5 kx
5 kx .TP 4
5 kx \fBanalytic-links\fR
5 kx The path to the file which contains meta tags with site ownership verificaton codes for engines such as \fIGoogle Search Console\fR or
5 kx \fIYandex Webmaster\fR. \fBcGit-ui\fR CGI Script reads the file \fBanalytic-links\fR in RAW format and includes it into <HEAD> tag of each HTML page.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIanalytic-links = '/analytics/links';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx Where the file \fI/analytics/links\fR may contains HTML tags like follow:
5 kx .RE
5 kx
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fI<meta name="google-site-verification" content="..." />\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx The file name should be defined relative of the path where \fBcGit-ui\fR CGI Script is installed. For example, if \fBcGit-ui\fR CGI Script installed
5 kx into \fI/srv/www/htdocs/cgit\fR directory and file name declared as \fI/analytics/links\fR then \fBcGit-ui\fR CGI Script will try to read the
5 kx file \fI/srv/www/htdocs/cgit/analytics/links\fR.
5 kx .RE
5 kx
5 kx .TP 4
5 kx \fBanalytic-scripts\fR
5 kx The path to the file which contains JavaScripts for engines such as \fIGoogle Search Console\fR or
5 kx \fIYandex Webmaster\fR. \fBcGit-ui\fR CGI Script reads the file \fBanalytic-scripts\fR in RAW format and includes it at the end of <HEAD> tag before </HEAD>
5 kx entry of each HTML page.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIanalytic-scripts = '/analytics/scripts';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx Where the file \fI/analytics/scripts\fR may contains code like follow:
5 kx .RE
5 kx
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fI
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 \fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx Please note that the \fI<script>\fR tags should be present in the \fI/analytics/scripts\fR because \fBcGit-ui\fR CGI Script reads this file
5 kx in RAW format and includes it as is.
5 kx .RE
5 kx
5 kx .RS 4
5 kx The variables \fBanalytic-links\fR and \fBanalytic-scripts\fR should be declared on the global level of the \fB/etc/cgit-ui.rc\fR
5 kx configuration file and cannot be overriden in a repository declaration.
5 kx .RE
5 kx
5 kx Donation variables:
5 kx
5 kx .RS 4
5 kx The \fBcGit-ui\fR 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 \fBdonate\fR variable to \fBdonate = 1\fR:
5 kx .RE
5 kx
5 kx .TP 4
5 kx \fBdonate\fR
5 kx The integer variable used to enable or disable donation dialogue.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIdonate = 1;\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBdonate-css\fR
5 kx The name of file contains the stylesheet for donation modal dialogue.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIdonate-css = '/donations/donate.css';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBdonate-html\fR
5 kx The name of file contains the HTML code of donation modal dialogue.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIdonate-html = '/donations/donate.html';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBdonate-js\fR
5 kx The name of file contains the javascript code for donation modal dialogue automation.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIdonate-js = '/donations/donate.js';\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx \fBcGit-ui\fR CGI Script includes these files at end of <BODY> tag just before the closing </BODY> tag. Unlike the others,
5 kx the \fBdonate-html\fR 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 \fI${donate-header}\fR
5 kx and \fI${donate-purpose}\fR:
5 kx .RE
5 kx
5 kx .TP 4
5 kx \fBdonate-header\fR
5 kx The title of the donation modal dialogue defined in the \fBdonate-html\fR file.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIdonate-header = "Donations";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .TP 4
5 kx \fBdonate-purpose\fR
5 kx The donation purpose used as value of <input value="..."> tag property in payment form of systems such as \fIPayPal\fR or \fIYandex.Money\fR.
5 kx Also this value can be used as a header of modal dialogue content.
5 kx Example declaration:
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fIdonate-purpose = "Support for our projects";\fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
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 .RE
5 kx
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fI
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 \fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx To show the modal dialogue in javascript code \fBdonate-js\fR the selector 'a.donate' should be used. For examle, like this:
5 kx .RE
5 kx
5 kx .PP
5 kx .in +6n
5 kx .EX
5 kx \fI
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 \fR
5 kx .EE
5 kx .in
5 kx
5 kx .RS 4
5 kx Where the variable \fIdialog\fR points to modal dialogue defined in the \fBdonate-html\fR file.
5 kx .RE
5 kx
5 kx
5 kx .SH "REPOSITORY DECLARATIONS"
5 kx The \fB/etc/cgit-ui.rc\fR config file should contains at least one repository declaration to be shown by the \fBcGit-ui\fR CGI Script.
5 kx When all expected variables declared in the global section the config file the repository declaration can be very simple:
5 kx .PP
5 kx .in +4n
5 kx .EX
5 kx \fI
5 kx repo 'tools' {
5 kx owner = "John Smith";
5 kx description = "John Smith's tools source code repository.";
5 kx }
5 kx \fR
5 kx .EE
5 kx .in
5 kx
5 kx The list of repositories can be splitted in several sections. The section has a name and can contains repository declarations only.
5 kx .PP
5 kx .in +4n
5 kx .EX
5 kx \fI
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 \fR
5 kx .EE
5 kx .in
5 kx
5 kx Global variables are propagate into repo sections but their values overrides by correspond repo variables.
5 kx
5 kx
5 kx .SH "SEE ALSO"
5 kx .BR cscmd (8)
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