From a97c673158bfd19dad46f5f5018aaf92df4a2605 Mon Sep 17 00:00:00 2001
From: pho4cexa <pho4cexa@orbital.rodeo>
Date: Fri, 9 Dec 2022 08:52:38 -0800
Subject: [PATCH] simplify main readme by moving "git forge" specifics
 elsewhere

just a suggestion; don't feel obligated to merge. you know technical
writing and documentation better than i do!
---
 README.md            | 135 +++++--------------------------------------
 build-a-git-forge.md | 125 +++++++++++++++++++++++++++++++++++++++
 2 files changed, 140 insertions(+), 120 deletions(-)
 create mode 100644 build-a-git-forge.md

diff --git a/README.md b/README.md
index 632942a..bad1704 100644
--- a/README.md
+++ b/README.md
@@ -11,7 +11,8 @@ Assuming the current directory is a Git repository, this command populates *DEST
 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*.
+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
 
@@ -20,14 +21,6 @@ You may also cause this directory to be automatically updated upon every `git pu
 - 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
@@ -41,116 +34,18 @@ no one is liable if this software breaks, deletes, corrupts, or ruins anything
     - [clojurian](https://wiki.call-cc.org/eggref/5/clojurian)
 - git
 
-## quickstart
+### installation
 
-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:
+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
 
-### installation
+if you wish, you may then uninstall the chicken scheme compiler.
 
-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.
+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
 
@@ -160,16 +55,16 @@ TODO
 
 - **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
-
+- **documentation/feature**: use post-update rather than post-receive hook for simplicity
+- **documentation**: also describe use with post-commit hook
+- **feature**: need better detection and rendering of binary files
+- **feature**: multi-page or collapse-able files list
+- **feature**: commit log
+- **feature**: branches and releases (tags)
 - **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**: customizable templates
 - **feature**: display binary files as output from binary-file analysis tools like hexdump, xxd, dumpelf, elfls, readelf, etc.?
+- **feature**: syntax highlighting?
 
 ## license: agpl-3.0+
 
diff --git a/build-a-git-forge.md b/build-a-git-forge.md
new file mode 100644
index 0000000..d01ff27
--- /dev/null
+++ b/build-a-git-forge.md
@@ -0,0 +1,125 @@
+# 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).
+
+Since **repo2html** is configured herein to output updated HTML files only in response to a `git push`, the git forge described here requires no complex server software like the ones above.
+Its webserver is configured to serve static html files 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.