GitGen

GitGen is a lightweight static website generator for local Git repositories written in Python. It scans a directory of Git repositories and produces a navigable, self-contained HTML website similar in spirit to cgit or GitWeb, but without any server-side dependencies.

The generated site includes a repository index, per-repository README rendering, file listings, commit history, and detailed commit views with diffs.

Features

GitGen generates a static HTML site with the following capabilities:

• Repository index page which lists all discovered Git repositories
• Automatic discovery of Git repositories under a base directory
• Repository overview pages with rendered README files
• Markdown rendering for README.md files
• File tree listings based on the current HEAD
• Commit history (last 50 commits per repository - configurable)
• Detailed commit pages with:
  • Full commit metadata
  • Tags pointing at relevant commits
  • Diffstat summary
  • Unified diff view (truncated to 500 lines - configurable)
• Safe HTML escaping throughout
• SEO meta
• Parallel repository processing for faster generation
• Version 2 introduced site generation caching for even faster builds and deployment.

All output is static HTML and CSS, suitable for hosting on any static web server.

Requirements

• Python 3.8 or newer
• Git installed and available in $PATH

Python dependencies:

Requires markdown.

Install with:

pip install markdown

Usage

1. Place the script somewhere on your system.
2. Edit the default base path to repositories:

GitRepoScanner:
def __init__(self, base_path: str = "/path/to/Git/repositories")

3. Run the script:

python3 gitgen.py

4. The generated site will be written to the git-website/ directory by default.

Open git-website/index.html in a browser or deploy the directory contents to a static web host.

Caching

Version 2 introduced site generation caching. A log gitgen-cache.json is created at first run which keeps track of the state of each repository by file path and HEAD hash. At subsequent runs, only repositories with new HEAD hashes (commits) are regenerated in full. Any new repositories are also added to the cache log and tracked moving forward.

• The log file gitgen-cache.json is output to the same directory as gitgen.py.
• Deleted repositories need to be removed manually from gitgen-cache.json.

The advantage is two-fold: 1. The caching removes the need to regenerate the entire site (all repos) at each run, ensuring faster build times. 2. When deploying to the remote web host, only changes are uploaded. This is assuming a solution like rsync or ftp is used, both of which are capable of transferring only newer local files to the remote web host.

The bandwidth savings on the remote deployment is significant, especially with a large number of repositories.

Directory Structure

The generated output has the following structure:

git-website/
├── index.html
├── main.css              # main.css is not generated*
├── repo-name/
│   ├── index.html        # README / overview
│   ├── files.html        # File listing
│   ├── commits.html      # Commit list
│   └── commits/
│       └── abc1234.html  # Individual commit pages

Each repository gets its own directory containing all related pages.

* main.css is not generated but included in this repo. Add it manually to the git-website directory.

README Rendering

GitGen looks for README files in the following order:

• README.md
• README.txt
• README
• readme.md
• readme.txt

Markdown READMEs are rendered using Python-Markdown with these extensions enabled:

• tables
• sane_lists
• fenced_code
• toc
• attr_list

Non-Markdown READMEs are rendered as escaped, pre-formatted text.

Licence

This project is made available under a GPL3 licence -- see COPYING for the full text.