Merge branch 'main' of git://git.m455.casa/repo2html

README.md

@@ -1,33 +1,41 @@
 # repo2html
 
-generates static html pages for browsing the contents of a git repository.
+A command-line tool that generates a static HTML representation of a Git
+repository.
 
-## basic usage
+## Page contents
 
-`repo2html <destination>`
+<!-- vim-markdown-toc GFM -->
 
-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.
+- [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)
 
-note: changes must be at least committed before they will appear in the html output.
+<!-- vim-markdown-toc -->
-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.
+## Features
-we describe how to use this technique to [build a static git forge](build-a-git-forge.md.html).
 
-## 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
 
-- static html files
+## Requirements
-- image support
-- markdown files are rendered as html
-- no resident background process
 
-## disclaimer
+- [Chicken Scheme](https://call-cc.org/)
-
+- The following Chicken Scheme eggs:
-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)
@@ -38,46 +46,108 @@ no one is liable if this software breaks, deletes, corrupts, or ruins anything
     - [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
+- Git
 
-### installation
+## Usage
 
-this compiles the binary `repo2html` and place it in `/usr/local/bin`.
+    repo2html <destination> <template-directory>
 
-1. ensure you're in the repo2html git repository
+Run `repo2html` inside the root directory of a Git repository or a bare Git
-2. as root, run `make dependencies`
+repository.
-3. run `make`
-4. run `make install` as root
 
-if you wish, you may then uninstall the chicken scheme compiler.
+- `<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.
 
-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.
+The HTML that's generated represents the state of the `HEAD` commit, not the
+current state of the work tree.
 
-## how it works
+## Installation
 
-TODO
+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.
 
-## todos
+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.
 
-- **documentation**: convert a lot of the stuff i (m455) made in the readme into an e2e tutorial
+**Note**: If you want to use `main.scm` as the `repo2html` executable, instead
-- **documenation**: scope the readme audience to folks who kind of know what they're doing with servers
+of compiling a static binary file, then run
-- **documentation/feature**: use post-update rather than post-receive hook for simplicity
+`cp main.scm /usr/local/bin/repo2html` as root.
-- **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+
+## Configuration
 
-Copyright 2022 [Jesse Laprade](https://m455.casa).
+You can `repo2html` by changing the following items:
-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
+- [Templates](#templates)
+- [Environment variables](#environment-variables)
+
+### Templates
+
+You can customize `repo2html` by editing the `assets/templates/default.html`,
+and then specifying the path to the `default.html` file as the second
+command-line argument when running `repo2html`.
+
+For example, if you placed a `default.html` file in `~/bin`, and you serve HTML
+files from `/var/www/git`, then you run `repo2html /var/www/git ~/bin`.
+
+### Environment variables
+
+You can provide a generic description by setting the `REPO2HTML_DESCRIPTION`
+environment variable, or by adding a description in a `description` file in the
+root directory of your Git repository.
+
+## Creating a Git forge on your web server
+
+Refer to
+[Create a Git forge with repo2html](html/documentation/create-a-git-forge-with-repo2html.md.html)
+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.
+
+## Alternative Git-to-HTML tools
 
 - [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/)
+
+## Existing Git forges
+
+- [NotABug](https://notabug.org/)
+- [Codeberg](https://codeberg.org/)
+- [sourcehut](https://sourcehut.org/)
+- [GitLab](https://gitlab.com/)
+- [Bitbucket](https://bitbucket.org/product/)
+- [SourceForge](https://sourceforge.net/)
+- [GitHub](https://github.com/)
+
+## Existing Git forge software
+
+- [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)
+
+## Todos
+
+- **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**: 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
+

assets/post-receive

@@ -6,10 +6,7 @@
 # The toplevel path containing directories of static pages
 [ "$REPO2HTML_PREFIX" ] || export REPO2HTML_PREFIX=/var/www/git
 # The toplevel clone url for repos.
-export REPO2HTML_CLONE_URL=git://git.example.com
-export REPO2HTML_TITLE=git.example.com
 export REPO2HTML_DESCRIPTION="sherry's git repositories"
-export REPO2HTML_H1=git.example.com
 
 # hueristic attempt to detect a reasonable default for the name of this repo
 # you may want to adjust this if you have e.g. sub-directories containing repos
@@ -52,4 +49,5 @@ else
     exit 1
 fi
 
-repo2html "$REPO2HTML_PREFIX/$repo_name"
+# the second argument here should be a directory containing "default.html"
+repo2html "$REPO2HTML_PREFIX/$repo_name" "path/to/directory/containing/template"

build-a-git-forge.md

@@ -1,126 +0,0 @@
-# how to use repo2html to build a git forge
-
-this document describes how one might use [repo2html](index.html) (this project) together with a webserver and some configuration to build a static git forge.
-
-a git forge is a website that presents one or more git repositories for visitors to browse,
-and also allows them to `git clone`, `pull`, and optionally `push` commits to and from those repositories,
-while automatically updating the browsable representation.
-
-some extant *git forge* services include:
-github,
-bitbucket,
-[gitlab](https://gitlab.com/),
-sourceforge,
-[sourcehut](https://sourcehut.org/), and
-[codeberg](https://codeberg.org/).
-
-software that can be used to build a self-hosted git forge includes:
-self-hosted [gitlab](https://about.gitlab.com/install/),
-[gogs](https://gogs.io/),
-[gitea](https://gitea.io/),
-[cgit](https://git.zx2c4.com/cgit/), and
-[gitweb](https://git-scm.com/book/en/v2/Git-on-the-Server-GitWeb).
-
-the git forge described here requires no continuously-running software beyond a simple webserver.
-we configure repo2html to output updated html files only in response to a `git push`,
-which the webserver then serves from disk.
-
-## 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`
-
-### 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.

documentation/create-a-git-forge-with-repo2html.md

@@ -0,0 +1,132 @@
+# Create a Git forge with repo2html
+
+This tutorial teaches you how to 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.
+
+A Git forge is a website that provides HTML representations of Git
+repositories, so visitors don't need to clone repositories to view their
+contents.
+
+## Page contents
+
+<!-- vim-markdown-toc GFM -->
+
+- [Requirements](#requirements)
+- [Prepare your server](#prepare-your-server)
+    - [Set up a git user](#set-up-a-git-user)
+    - [Set up nginx](#set-up-nginx)
+    - [Install repo2html](#install-repo2html)
+    - [Set up a post-receive hook](#set-up-a-post-receive-hook)
+    - [Enable cloning over git://](#enable-cloning-over-git)
+- [Test your post-receive hook locally](#test-your-post-receive-hook-locally)
+
+<!-- vim-markdown-toc -->
+
+## 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
+- nginx
+
+## Prepare your server
+
+This section uses `example.com` as a placeholder value. Ensure you replace
+`example.com` with your own domain when following the procedures 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 to your server.
+- 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`.
+
+### Set 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`.
+
+After you've set up a git user, follow all procedures that don't require root
+as the git user.
+
+### Set 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`.
+
+### Install repo2html
+
+Ensure you're in the repo2html git repository, and follow the steps below:
+
+1. As root, run `make dependencies`.
+2. Run `make`.
+3. As root, run `make install`.
+
+### Set up a post-receive hook
+
+1. Ensure you're in the `repo2html` Git repository.
+2. Run `mkdir ~/bin`.
+3. Run `echo "PATH="~/bin:$PATH" >> ~/.profile`.
+4. Run `cp assets/post-receive ~/bin`.
+5. Run `chmod u+x ~/bin/post-receive`.
+6. Run `ln -sf ~/bin/post-receive ~/projects/my-repository/hooks/post-receive`.
+7. Run `cp assets/templates/default.html ~/bin`.
+8. In the `assets/post-receive` file, change
+   `path/to/directory/containing/template` to `~/bin`
+
+### Enable cloning over git://
+
+1. Ensure you're in the `repo2html` Git repository.
+2. As root, run `cp assets/git-daemon.service /etc/systemd/system`.
+3. As root, run `systemctl enable --now git-daemon.service`.
+
+## Test your post-receive hook locally
+
+This section uses `example.com` as a placeholder value. Ensure you replace
+`example.com` with your own domain when following the procedures 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`.
+8. Navigate to `https://git.example.com/my-repository` in your browser.
+
+
+
+