# 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)
- [Setting up a Git forge on your web server](#setting-up-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/), and 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/templates`, and you serve HTML files from `/var/www/git`, then you run `repo2html /var/www/git ~/bin/templates`.

### 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](documentation/create-a-git-forge-with-repo2html.md.html) 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](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