# repo2html

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

## Page contents

<!-- vim-markdown-toc GFM -->

- [Features](#features)
- [Requirements](#requirements)
- [Usage](#usage)
- [Installation](#installation)
- [Configuration](#configuration)
    - [Templates](#templates)
    - [Environment variables](#environment-variables)
- [Creating a Git forge on your web server](#creating-a-git-forge-on-your-web-server)
- [Alternative Git-to-HTML tools](#alternative-git-to-html-tools)
- [Existing Git forges](#existing-git-forges)
- [Existing Git forge software](#existing-git-forge-software)
- [Todos](#todos)

<!-- vim-markdown-toc -->

## 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](https://call-cc.org/)
- The following Chicken Scheme eggs:
    - [clojurian](https://wiki.call-cc.org/eggref/5/clojurian)
    - [ersatz](https://wiki.call-cc.org/eggref/5/ersatz)
    - [lowdown](https://wiki.call-cc.org/eggref/5/lowdown)
    - [scss](https://wiki.call-cc.org/eggref/5/scss)
    - [srfi-1](https://wiki.call-cc.org/eggref/5/srfi-1)
    - [srfi-13](https://wiki.call-cc.org/eggref/5/srfi-13)
    - [srfi-14](https://wiki.call-cc.org/eggref/5/srfi-14)
    - [sxml-transforms](https://wiki.call-cc.org/eggref/5/sxml-transforms)
    - [symbol-utils](https://wiki.call-cc.org/eggref/5/symbol-utils)
    - [utf8](https://wiki.call-cc.org/eggref/5/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](#templates)
- [Environment variables](#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.

## Creating a Git forge on your web server

Refer to
[Create a Git forge with repo2html](html/documentation/create-a-git-forge-with-repo2html.md.html)
to learn how use `repo2html` in a `post-receive` hook to auto-generate HTML
representations of bare Git repositories on a remote web server after you `git
push` to them.

## Alternative Git-to-HTML tools

- [stagit](https://codemadness.org/git/stagit/file/README.html)
- [depp](https://git.8pit.net/depp.git/)
- [git-arr](https://blitiri.com.ar/p/git-arr/)

## Existing Git forges

- [NotABug](https://notabug.org/)
- [Codeberg](https://codeberg.org/)
- [sourcehut](https://sourcehut.org/)
- [GitLab](https://gitlab.com/)
- [Bitbucket](https://bitbucket.org/product/)
- [SourceForge](https://sourceforge.net/)
- [GitHub](https://github.com/)

## Existing Git forge software

- [GitLab](https://about.gitlab.com/install/)
- [Gogs](https://gogs.io/)
- [Gitea](https://gitea.io/)
- [cgit](https://git.zx2c4.com/cgit/)
- [GitWeb](https://git-scm.com/book/en/v2/Git-on-the-Server-GitWeb)
- [legit](https://git.icyphox.sh/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