cgit

cgit is a lightweight Git repository browser for the web written in C. It is also easily configurable, both globally and per repository, with a simple configuration file.

Prerequisites

cgit simply allows you to view existing Git repositories. AFAIK it does not allow creating new repositories, pull requests, bug reports, or other Github/Gitlab like functionality.

That being said, creating your own repositories is easy. Simply follow my Git Cheat sheet and become a serious developer today!

You should end up with a directory on your system (I typically use /home/git for reasons explained in the cheat sheet) populated with repo-x.git directories. This is what cgit wants to see!

Hosting cgit without Docker

Hosting cgit without Docker is actually the official method, and thus is extremely simple. It doesn’t have many dependencies, and it is available in most distributions by default.

The main reason I choose to use docker is because of docker compose and infrastructure as code. I can simply wipe my server, install docker, clone my webservices repository, run docker compose up -d and I’m back up and running like nothing happened!

Choosing a Docker image

Unfortunately, there is no official cgit docker image. So you either have to choose a community maintained one or create your own.

Good, well-documented, well-maintained, unofficial images are difficult to find. And they can be difficult to compare too if you aren’t already familiar with the software.

I currently use joseluisq/alpine-cgit since it seems like it is currently one of those well-maintained unicorns. I prefer an Alpine based image since they are generally less bloated than their counterparts, and this image uses Nginx over Apache which is preferred as well. However, I cannot vouch for this image long term since, once again, there’s no telling how long the maintainer will continue supporting it.

Docker Compose

I use Docker Compose to deploy all my containers because it is basically just infrastructure as code for containers.

Here is a simple docker-compose.yaml to get you started with cgit:

1
2
3
4
5
6
7
8

services:
  cgit:
    image: joseluisq/alpine-cgit
    restart: always
    volumes:
      - /home/git:/srv/git:ro  # Repos
    ports:
      - 7000:80

This configuration will host the Git repositories stored in /home/git on port 7000. Just run docker compose up -d on whatever directory you save this file in.

Configuring cgit

cgit can be configured by using a cgitrc file. When using docker, the default cgitrc can be replaced by mounting your new cgitrc over the original in the container.

Some features I won’t cover, but you might be interested in are:

• Change logos and site descriptions
• About pages for repositories
• Plugin support
• Syntax highlighting plugin for source files
• Advanced filtering framework using a script file or the built-in lua interpreter

The Arch Wiki has a decent article on how to do several of those things.

But really, I am happy with the default configuration.

Repo-specific cgitrc

You can also override any settings prefixed with ‘repo.’ with a repo-specific cgitrc file.

This allows you to hide/ignore repositories, as well as give them names and descriptions for cgit to display.

Simply create a file called cgitrc in the repo’s main directory, alongside the files you would typically find in the .git folder if you cloned the repo. Eg.

branches/  cgitrc  config  description  HEAD  hooks/  info/  objects/  refs/

Now in this file, you can set the repo-specific settings. Just remember to remove the ‘repo.’ prefix so that, for example, repo.name would become just name.

Here’s an example:

name=My cgit Repo
desc=A description of my repo
readme=master:docs/introduction.md

Other useful settings include hiding or ignoring certain repos. hide=1 will hide the repository on the main index page, and ignore=1 will prevent cgit from serving the repo altogether.