246 lines
9.3 KiB
Markdown
246 lines
9.3 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 "" (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
|