Cgit is a web based viewer of Git projects similar to Gitweb. The main difference is that Cgit is designed to be fast.

Requirements

The following instructions were tested using Debian unstable with the latest versions of Git (1.8.3.1) and Cgit (0.9.2). For the web server Apache 2.4 was used.

Cgit Installation

It is assumed that Git and Gitolite have already been installed and configured. The following is an abbreviated version of the instructions in the README included with Cgit.

This installation is in to a user specific directory (/home/git) as opposed to being system wide.

The first step is to clone the project in to its own cgit-dist directory. We don’t want to use cgit/ because that is where it will be installed.

git:~/$ git clone git://git.zx2c4.com/cgit cgit-dist

Cgit depends on Git so this be installed in to the cloned directory.

git:~/$ cd cgit-dist/
git:~/cgit-dist$ git submodule init
git:~/cgit-dist$ git submodule update

Before compiling Cgit make sure the ssl development headers are installed.

apt-get install libssl-dev

The following shows the changes that are needed to the Cgit Makefile in order to configure it to install in to /home/git.

--- Makefile.orig    2013-06-28 16:51:02.432555828 -0700
+++ Makefile    2013-06-28 16:52:38.656552492 -0700
@@ -2,11 +2,11 @@
 
 CGIT_VERSION = v0.9.2
 CGIT_SCRIPT_NAME = cgit.cgi
-CGIT_SCRIPT_PATH = /var/www/htdocs/cgit
+CGIT_SCRIPT_PATH = /home/git/cgit/www
 CGIT_DATA_PATH = $(CGIT_SCRIPT_PATH)
-CGIT_CONFIG = /etc/cgitrc
-CACHE_ROOT = /var/cache/cgit
-prefix = /usr
+CGIT_CONFIG = /home/git/cgit/etc/cgitrc
+CACHE_ROOT = /home/git/cgit/var/cache/cgit
+prefix = /home/git/cgit/usr
 libdir = $(prefix)/lib
 filterdir = $(libdir)/cgit/filters
 docdir = $(prefix)/share/doc/cgit

Then run:

make
make install

Initial Cgit Configuration

The main configuration file for Cgit is located in etc/cgitrc. Or more specificially, /home/git/cgit/etc/cgitrc, in this example.

The following is the example cgitrc. The most important options to configure are: clone-url, css, enable-git-config, logo, project-list and scan-path.

# Enable caching of up to 1000 output entriess
cache-size=1000

# cache time to live 
cache-dynamic-ttl=5
cache-repo-ttl=5
cache-repo-ttl=5

# Specify some default clone urls using macro expansion
clone-url=git://hudson.localdomain/$CGIT_REPO_URL git@hudson.localdomain:$CGIT_REPO_URL

# Specify the css url
css=/cgit.css

# Show owner on index page
enable-index-owner=1

# Source gitweb.description, gitweb.owner from each project config
enable-git-config=1

# Allow http transport git clone
enable-git-clone=1

# Show extra links for each repository on the index page
enable-index-links=1

# Remove .git suffix from project display
remove-suffix=1

# Enable ASCII art commit history graph on the log pages
enable-commit-graph=1

# Show number of affected files per commit on the log pages
enable-log-filecount=1

# Show number of added/removed lines per commit on the log pages
enable-log-linecount=1

# Sort branches by date
branch-sort=age

# Add a cgit favicon
favicon=/favicon.ico

# Use a custom logo
logo=/cgit.png

# Enable statistics per week, month and quarter
max-stats=quarter

# Set the title and heading of the repository index page
root-title=hudson.localdomain Git repositories

# Set a subheading for the repository index page
root-desc=tracking the foobar development

# Include some more info about example.com on the index page
root-readme=/home/git/cgit/www/about.htm

# Allow download of tar.gz, tar.bz2 and zip-files
snapshots=tar.gz tar.bz2 zip

##
## List of common mimetypes
##

mimetype.gif=image/gif
mimetype.html=text/html
mimetype.jpg=image/jpeg
mimetype.jpeg=image/jpeg
mimetype.pdf=application/pdf
mimetype.png=image/png
mimetype.svg=image/svg+xml

# Highlight source code with python pygments-based highligher
source-filter=/home/git/cgit/filters/syntax-highlighting.py

# Format markdown, restructuredtext, manpages, text files, and html files
# through the right converters
about-filter=/home/git/cgit/filters/about-formatting.sh

##
## Search for these files in the root of the default branch of repositories
## for coming up with the about page:
##
readme=:README.md
readme=:readme.md
readme=:README.mkd
readme=:readme.mkd
readme=:README.rst
readme=:readme.rst
readme=:README.html
readme=:readme.html
readme=:README.htm
readme=:readme.htm
readme=:README.txt
readme=:readme.txt
readme=:README
readme=:readme
readme=:INSTALL.md
readme=:install.md
readme=:INSTALL.mkd
readme=:install.mkd
readme=:INSTALL.rst
readme=:install.rst
readme=:INSTALL.html
readme=:install.html
readme=:INSTALL.htm
readme=:install.htm
readme=:INSTALL.txt
readme=:install.txt
readme=:INSTALL
readme=:install

##
## List of repositories.
## PS: Any repositories listed when section is unset will not be
##     displayed under a section heading
## PPS: This list could be kept in a different file (e.g. '/etc/cgitrepos')
##      and included like this:
##        include=/etc/cgitrepos
##

project-list=/home/git/projects.list
scan-path=/home/git/repositories

Configuring Apache

After installing Cgit, the next step is to configure Apache.

When reloading the configuration the result in the browser may be incorrect due to the effects of caching. To guarantee that everything is restarted it is recommended to restart Apache (apachectl graceful), clear Cgit’s cache (rm -f var/cache/cgit/*), and clear the browser cache.

Under Debian the following Apache configurations can be added as new sites under /etc/apache2/sites-available and then linked to sites-enabled like usual.

A Simple Apache Configuration

The following is a simple site configuration. It takes care of redirecting root to the /cgit.cgi/ and all other links are derived from there.

<VirtualHost *:80>
    ServerName cgit.hudson.localdomain

    DocumentRoot /home/git/cgit/www

    <Directory "/home/git/cgit/">
        Options ExecCGI
        AddHandler cgi-script .cgi
        Require all granted
        AllowOverride None
    </Directory>

    <IfModule mod_rewrite.c>
        RewriteEngine on
        RewriteRule ^/$ /cgit.cgi/ [R]
    </IfModule>

    ErrorLog /home/git/cgit/log/error.log
    CustomLog /home/git/cgit/log/access.log combined

</VirtualHost>

# vim: syntax=apache ts=4 sw=4 sts=4 sr noet

An Apache Configuration With Clean Urls

A more complicated version that cleans up the urls by eliminating cgit.cgi is given below.

<VirtualHost *:80>
    ServerName cgit.hudson.localdomain

    DocumentRoot /home/git/cgit/www

    ScriptAlias / /home/git/cgit/www/cgit.cgi

    <Directory "/home/git/cgit/www">
        Options ExecCGI
        AddHandler cgi-script .cgi
        DirectoryIndex cgit.cgi
        Require all granted
        AllowOverride None
    </Directory>

    <IfModule mod_rewrite.c>
        RewriteEngine on
        # Don't modify the urls to *.png and *.css files
        RewriteRule ^/(.*\.png)$ /$1 [L]
        RewriteRule ^/(.*\.css)$ /$1 [L]
        # remove cgit.cgi from the url
        RewriteRule ^/(.*)$ /cgit.cgi/$1 [L]
    </IfModule>

    ErrorLog /home/git/cgit/log/error.log
    CustomLog /home/git/cgit/log/access.log combined

</VirtualHost>

# vim: syntax=apache ts=4 sw=4 sts=4 sr noet

Configuration Check

If the configuration of Cgit and Apache have worked properly the main page should look similar to below. The actual project and names may be different.

Config Check

Cgit Configuration Details

Missing Description and Owner

The Owner and Description may appear to be blank or undefined. This can be caused by a misconfiguration of Gitolite.

The Gitolite config file (gitolite-admin/conf/gitolite.conf) allows for an owner and description to be added as shown below.

hello "Jeremiah Mahler" = "Git practice project"
repo hello
    RW+     = @all

To get Gitolite to provide values that work with Cgit the following changes should be made to the gitolite.rc.

git@hudson:~$ diff -u .gitolite.rc.orig .gitolite.rc
--- .gitolite.rc.orig    2013-06-30 15:56:40.107581065 -0700
+++ .gitolite.rc    2013-06-30 15:58:34.835577087 -0700
@@ -21,7 +21,7 @@
     UMASK                           =>  0022,
 
     # look for "git-config" in the documentation
-    GIT_CONFIG_KEYS                 =>  '',
+    GIT_CONFIG_KEYS                 =>  '.*',
 
     # comment out if you don't need all the extra detail in the logfile
     LOG_EXTRA                       =>  1,
@@ -126,7 +126,7 @@
             # 'upstream',
 
             # updates 'description' file instead of 'gitweb.description' config item
-            # 'cgit',
+            'cgit',
 
         # performance, logging, monitoring...
 
git@hudson:~$

Now Cgit should show a proper Description and Owner when these are present in gitolite-admin/conf/gitolite.conf.

About, Internal Server Error

Another problem that may appear with a new Cgit install is that the about page returns Internal Server Error.

The first option is to disable the about page. This can be done by commenting out the root.readme option.

#root-readme=/home/git/cgit/www/about.htm

The second option is to actually fix the problem. The about functionality is actually quite useful. It will automatically display README files from a project similar to how Github does.

In one case it is caused by a shell script syntax error. In the Apache error_log you may see entries like the following.

[Sun Jun 30 12:02:16.388856 2013] [cgi:error] [pid 15448] [client 127.0.0.1:51966] AH01215: /home/git/cgit/filters/about-formatting.sh: 21: /home/git/cgit/filters/about-formatting.sh: Syntax error: redirection unexpected, referer: http://cgit.hudson.localdomain/

This redirection unexpected error occurs when running /bin/sh. But on Debian /bin/sh maps to /bin/dash. And this error occurs the <<< operator is not supported in dash, only bash (Bash Here Strings).

To fix the problem edit filters/about-formatting.sh and change

#!/bin/sh

#!/bin/bash

Jeremiah Mahler

Setting up Cgit with Gitolite