repo2html/README.md

repo2html

repo2html generates static HTML pages for browsing the contents of a Git repository.

basic usage

repo2html DESTINATION

Assuming the current directory is a Git repository, this command populates DESTINATION with HTML files that provide a web-browsable view of the contents of the git 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 (if any).

You may also cause this directory to be automatically updated upon every git push, by invoking repo2html as a Git post-receive hook.

features

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

caveats

• need better detection and rendering of binary files
• directory tree is shown as a flat list of files
• no commit log yet
• no line numbers yet
• no customizable templates yet

disclaimer

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

requirements

• chicken scheme, and eggs:
  • utf8
  • lowdown
  • sxml-transforms
  • clojurian
• git

quickstart

1. ensure you've set up a web directory and have replaced the REPO2HTML_PREFIX value in the post-receive and git-daemon.service files
2. you've created a git user, and are logged in as the git user
3. as root, run make dependencies
4. run make
5. as root, run make install
6. run mkdir ~/projects && git init --bare my-repository
7. run cp post-receive ~/projects/my-repository/hooks/
8. run chmod u+x ~/projects/my-repository/hooks/post-receive
9. run cp git-daemon.service /etc/systemd/system/

server setup

this section uses example.com as a placeholder value. ensure you replace example.com with your own domain below.

this section assumes the following about your server:

• you've generated public and private ssh keys on your local machine
• you can access your server through ssh and have root access
• you manage your firewall with ufw
• you use nginx as your web server
• you use letsencrypt to manage TLS certificates
• you've added an A record for git.example.com

setting up a git user

ensure you're in the repo2html git repository, and follow the steps below:

1. as root, run adduser git
2. as root, run mkdir /var/www/git && chown git:git /var/www/git
3. as root, run ufw allow 9418
4. run su git
5. run mkdir ~/.ssh && chmod 700 ~/.ssh
6. run touch ~/.ssh/authorized_keys && chmod 600 ~/.ssh/authorized_keys
7. add your public ssh key from your local machine to ~/.ssh/authorized_keys
8. run mkdir ~/projects
9. run git init --bare my-repository

setting up nginx

1. as root, add the following contents to /etc/nginx/sites-available/git.example.com:

    server {
        root /var/www/git;
        index index.html;
        server_name git.example.com;
    }
   

2. as root, run ln -s /etc/nginx/sites-available/git.example.com /etc/nginx/sites-enabled/

3. as root, run nginx -t to test your nginx configuration

4. as root, run certbot, and follow the prompts

5. as root, run systemctl restart nginx

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. as root, run make dependencies
3. run make

installation

ensure you're in the repo2html git repository, and follow the steps below:

1. run make install as root
2. run cp post-receive ~/projects/my-repository/hooks/
3. run chmod u+x ~/projects/my-repository/hooks/post-receive
4. run cp git-daemon.service /etc/systemd/system/ as root
5. run systemctl enable --now git-daemon.service as root

using repo2html as a post-receive hook

this section uses example.com as a placeholder value. ensure you replace example.com with your own domain below.

on your local machine, follow the steps below:

1. run git init my-repository
2. run cd my-repository
3. run echo "hello" > my-file.txt
4. run git add my-file.txt
5. run git commit -m "my first commit"
6. run git remote add origin git@example.com:~/projects/my-repository
7. run git push

configuration

this section uses example.com as a placeholder value. ensure you replace example.com with your own domain below.

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:

• REPO2HTML_PREFIX: the web directory where repo2html generates static git repositories. for example, /var/www/git/.
• REPO2HTML_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.
• REPO2HTML_TITLE: the text that populates the <title> html tag.
• REPO2HTML_DESCRIPTION: a string that populates the description meta information about your git repository.
• REPO2HTML_H1: the text that populates the <h1> html tag.

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

hopes

• feature: clickable line numbers in source files
• feature: make repos with more files and directories less daunting (recursively generate a files list page for each directory in a repo?)
• feature: nav links: Releases, Branches, Commits (Log)

should we...?

• feature: display binary files as output from binary-file analysis tools like hexdump, xxd, dumpelf, elfls, readelf, etc.?

license: agpl-3.0+

Copyright 2022 Jesse Laprade. This software is released under the terms of the GNU Affero General Public License, version 3 or any later version.

alternatives

• stagit
• depp
• git-arr