repo2html/README.md

repo2html

A command-line tool that generates a static HTML representation of a Git repository.

Page contents

• Features
• Requirements
• Usage
• Installation
• Configuration
  • Templates
  • Environment variables
• Setting up a Git forge on your web server
• Alternative Git-to-HTML tools
• Existing Git forges
• Existing Git forge software
• Todos

Features

• Static html files
• Customizable templates
• Can be used as a standalone command-line tool, or in a Git hook
• Built-in, plaintext issue support
• Image support
• Markdown files are rendered as HTML
• No resident background process

Requirements

• Chicken Scheme, and eggs:
  • clojurian
  • ersatz
  • lowdown
  • scss
  • srfi-1
  • srfi-13
  • srfi-14
  • sxml-transforms
  • symbol-utils
  • utf8
• Git

Usage

repo2html <destination> <template-directory>

Run repo2html inside the root directory of a Git repository or a bare Git repository.

• <destination> is the path to the directory that you want the HTML files to be generated in.
• <template-directory> is the path to the directory that contains a default.html file. Refer to assets/templates/default.html for an example default.html file.

The HTML that's generated represents the state of the HEAD commit, not the current state of the work tree.

Installation

This section guides you through installing the required dependencies, compiling a binary, and then installing the binary. By default, repo2html installs into the /usr/local/bin directory.

1. Ensure you're in the repo2html git repository.
2. As root, run make dependencies to install the required Chicken Scheme eggs.
3. Run make to compile a static repo2html binary in the current directory.
4. As root, run make install to copy the repo2html binary into the /usr/local/bin directory.

Note: If you want to use main.scm as the repo2html executable, instead of compiling a static binary file, then run cp main.scm /usr/local/bin/repo2html as root.

Configuration

You can repo2html by changing the following items:

• Templates
• Environment variables

Templates

You can customize repo2html by editing the assets/templates/default.html, and then specifying the path to the default.html file as the second command-line argument when running repo2html.

For example, if you placed a default.html file in ~/bin, and you serve HTML files from /var/www/git, then you run repo2html /var/www/git ~/bin.

Environment variables

You can provide a generic description by setting the REPO2HTML_DESCRIPTION environment variable, or by adding a description in a description file in the root directory of your Git repository.

Setting up a Git forge on your web server

Refer to Create a Git forge with repo2html to learn how use repo2html as a post-receive hook to auto-generate HTML webpages for bare Git repositories on a remote web server.

Alternative Git-to-HTML tools

• stagit
• depp
• git-arr

Existing Git forges

• NotABug
• Codeberg
• sourcehut
• GitLab
• Bitbucket
• SourceForge
• GitHub

Existing Git forge software

GitLab Gogs Gitea cgit GitWeb legit

Todos

• documentation/feature: use post-update rather than post-receive hook for simplicity
• documentation: also describe use with post-commit hook
• documentation: describe readme, license, and issues behaviours
• feature: multi-page or collapse-able files list
• feature: branches and releases (tags)
• feature: clickable line numbers in source files
• feature: display binary files as output from binary-file analysis tools like hexdump, xxd, dumpelf, elfls, readelf, etc.?
• feature: syntax highlighting?
• feature: markdown-render git log text
• feature: other mechanisms for header id application like uniqueness checking, sequential numbering