137 lines
5.2 KiB
Markdown
137 lines
5.2 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)
|
|
- [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`, 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](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
|
|
|