repo2html/README.md

# repo2html

a post-receive hook that generates an html view of a git repository.

## features

- static html files
- no background process other than git-daemon
- default repository view is an html-rendered README.md file

## caveats

- binary file contents are just... shown
- images don't render
- directory tree is shown as a flat list of files, so git repositories with
  many files and directories will look awful
- no commit log (yet?)
- no line numbers (yet?)

## disclaimer

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

## requirements

- [chicken scheme](https://call-cc.org/)
- [utf8 egg](https://wiki.call-cc.org/eggref/5/utf8)
- [lowdown egg](https://wiki.call-cc.org/eggref/5/lowdown)
- git

**note**: if you have chicken scheme installed, then you can install the eggs
above by running `make dependencies` as root.

## compilation

chicken scheme runs faster if it's compiled to a binary file. by default, the
binary is named `repo2html`, and is installed in `/usr/local/bin`.

to compile repo2html into a binary file, follow the steps below:

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

## configuration

you can configure repo2html by changing environment variables in the `post-receive` hook file.

for details about the environment variables, refer to the list below:

- `GIT_WWW`: the web directory where repo2html generates static git repositories. for example, `/var/www/git/`.
- `GIT_WWW_CLONE_URL`: the url that people will use when downloading your git repository. if you have git-daemon set up, then you can prefix the url with `git://`. otherwise, prefix the url with `http://`. for example, `git://git.example.com`. **note**: avoid slashes at the end of the url.
- `GIT_WWW_TITLE`: the text that populates the `<title>` html tag.
- `GIT_WWW_DESCRIPTION`: a string that populates the `description` meta information about your git repository.
- `GIT_WWW_H1`: the text that populates the `<h1>` html tag.

## how it works

TODO

## todos

- ☐ if no README.md file exists in the root directory of the repository, then don't create the "about" nav link. instead, make the files page the index.html
- ☐ add a "license" nav link if a LICENSE file exists in the root directory of the repository. if no LICENSE file exists, then don't create the "license" nav link
- ☐ add a "contributors" nav link

## hopes

- ☐ clickable line numbers in source files
- ☐ render images
- ☐ make repos with more files and directories less daunting (recursively generate a files list page for each directory in a repo?)
- ☐ nav link: Releases