repo2html/README.md

# 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.

## Templates

You can customize `repo2html` by modifying the template file
`assets/templates/default.html`, and then specifying the directory containing
your modified `default.html` as the second command-line argument when running
`repo2html`.

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

Templates are rendered using [ersatz](https://wiki.call-cc.org/eggref/5/ersatz),
whose syntax is similar to the [Jinja2](https://palletsprojects.com/p/jinja/)
templating system.

If you use the `include` directive in your modified `default.html` template
file, `repo2html` will look for the templates to be included in that same
specified directory, where your `default.html` template lives.

The following variables are available to templates:

- source_files_list: a list of all the files in the repo.
- repository_description: a short description of the repo, if provided. See configuration.
- repository_name: the name of the repo. See configuration.
- repository_path: the URL path from the forge root to the repo.
- repository_path_parent: repository_path without the repo itself.
- repository_ancestors: a list of each path element in repository_path_parent
- readme_file: the filename of the README file, if any. used for the "about" link.
- license_file: the filename of the LICENSE file, if any. used for the "license" link.
- issues_file: if any files exist in ISSUES/, this will be set to "ISSUES".
- repo2html_version: the blob hash of main.scm in this repository.
- source_file: the filename of the file being rendered.
- root: always "" (TODO: omit this?)
- elements: a list of each path element leading to the file being rendered
- basename: the filename being rendered, with one extension removed
- extension: the extension removed in basename
- relative_root: "html/" if the current file is "/index.html" otherwise ""

## Configuration

`repo2html` understands the following configuration settings.

These settings are typically set using `git config` like

```git config repo2html.<setting> value```

Environment variables may also be used for configuration, and take precedence over settings in `git config`:

```export REPO2HTML_<SETTING>=value```

### Name

- `$REPO2HTML_NAME` or
- `git config repo2html.name`
- default: the repo's directory name

Your repository "name" is, by default, the name of the directory as specified in the first argument provided to `repo2html`.

You may override this if you prefer a more human-friendly name, for example:

`git config repo2html.name "Git Repository To Hypertext Markup Language Generator"`

This affects the template variable `repository_name` but not `repository_path`.

### Description

- `$REPO2HTML_DESCRIPTION` or
- `git config repo2html.description` or
- edit the `.git/description` file
- default: ""

A short description for the repo.
This may also be set by adding a description in a `description` file in the root directory of your Git repository.
(This is the same mechanism that `cgit` uses.)

### ForgeRoot

- `$REPO2HTML_FORGEROOT` or
- `git config repo2html.forgeroot`

This is a helper intended for use when [building a git forge](#creating-a-git-forge-on-your-web-server).

It specifies the filesystem path to the directory containing (possibly a hierarchy of) html output directories.

This affects the template variables `repository_path`, `repository_path_parent`, and `repository_ancestors`, when the repo is found to be in a subdirectory of `ForgeRoot`. 

Example:

With forgeroot unset, the command  
`repo2html /var/www/repos/mike/projecta/repo1 /path/to/templates`  
will set the variable `repository_path` to `repo1`

With forgeroot set to `/var/www/repos`, the command  
`repo2html /var/www/repos/mike/projecta/repo1 /path/to/templates`  
will set the variable `repository_path` to `mike/projecta/repo1`

When your forge is built with a shared git user, it's convenient to use --global to specify this just once, like:

`sudo -u git git config --global repo2html.forgeroot /var/git-repos/`

## Creating a Git forge on your web server

Refer to
[Create a Git forge with repo2html](documentation/create-a-git-forge-with-repo2html.md)
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.

## Alternatives

### Git Repo Static Page Generators

Other tools like `repo2html`, that generate a set of HTML files representing the contents of a git repository.

- [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/)

### Git Forge Software

Software for self-hosting or building your own collection of many git repos for potentially multiple users.

- [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)
- [gitile](https://git.lepiller.eu/gitile)
- [pagure](https://pagure.io/pagure)

### Git Forge Services

Third-party-hosted services that will host browsable code repositories.

- [NotABug](https://notabug.org/)
- [Codeberg](https://codeberg.org/)
- [sourcehut](https://sourcehut.org/)
- [GitLab](https://gitlab.com/)
- [SourceForge](https://sourceforge.net/)
- Red Hat [pagure](https://pagure.io/pagure)
- Atlassian Bitbucket
- Microsoft GitHub

## Todos

- **documentation**: move all of these TODOs into ISSUES/
- **documentation**: provide a precompiled binary download
- **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**: diffs for each commit
- **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
- **feature**: remotes, upstream identification, and tracking branch status
- **feature**: reimplement a table-of-contents mechanism because i don't use m455's vim-markdown-toc plugin and they get out-of-sync