199 lines
7.5 KiB
Markdown
199 lines
7.5 KiB
Markdown
# 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 empty. # TODO FIXME
|
|
- `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 empty.
|
|
|
|
## 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/)
|