# repo2html

generates static html pages for browsing the contents of a git repository.

## basic usage

`repo2html <destination>`

run from a git repository, this command populates the directory `<destination>` with html files that provide a web-browsable view of the contents of repository.

note: changes must be at least committed before they will appear in the html output.
more precisely: the html output represents the state of the `HEAD` commit, not that of the current work-tree.

you may also cause this html directory to be automatically updated upon every `git push`, by invoking repo2html from a git hook.
we describe how to use this technique to [build a static git forge](build-a-git-forge.md.html).

## features

- static html files
- image support
- markdown files are rendered as html
- no resident background process

## disclaimer

no one is liable if this software breaks, deletes, corrupts, or ruins anything

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

### installation

this compiles the binary `repo2html` and place it in `/usr/local/bin`.

1. ensure you're in the repo2html git repository
2. as root, run `make dependencies`
3. run `make`
4. run `make install` as root

if you wish, you may then uninstall the chicken scheme compiler.

if you prefer, the file `main.scm` may be used as the repo2html executable instead of compiling a binary file, but it will be slower, and requires that the chicken scheme interpreter remain installed on your system.

## how it works

TODO

## todos

- **documentation**: convert a lot of the stuff i (m455) made in the readme into an e2e tutorial
- **documenation**: scope the readme audience to folks who kind of know what they're doing with servers
- **documentation/feature**: use post-update rather than post-receive hook for simplicity
- **documentation**: also describe use with post-commit hook
- **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

## license: agpl-3.0+

Copyright 2022 [Jesse Laprade](https://m455.casa).
This software is released under the terms of the [GNU Affero General Public License](https://www.gnu.org/licenses/agpl.html), version 3 or any later version.

## alternatives

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