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 `sudo make dependencies`.

## quickstart

    on your server, run the following commands, changing anything occurs between angled brackets ("<" and ">"):
    adduser git
    mkdir /var/www/git
    chown git:git /var/www/git
    cp git-daemon.service /etc/systemd/system/
    ufw allow 9418
    systemctl enable --now git-daemon.service
    su - git
    mkdir projects
    clone this repository
    cd into this repository
    sudo make dependencies
    make
    sudo make install
    edit the post-receive file
    cp post-receive <path/to/bare/git/repository>/hooks/
    chmod u+x <path/to/bare/git/repository>/hooks/post-receive
    then in a git repository on your local machine, run git remote add origin git@<example.com>:~/projects/<repository-name>
    git push

## compilation

    sudo make dependencies
    make
    sudo make install

## server setup

TODO (git user, ssh, ufw ports, web directory, git-daemon, mkdir /home/git/projects, post-receive hook, systemd service)

## usage

TODO: just talk about how the post-receive hook works. shouldn't be too long

## configuration

TODO: describe environment variables in post-receive hook

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