github/repo2html
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Updated documentation and cleaned up directory tree

Browse source 
- Updated documentation, so it's very nice for pho4cexa <3
- Moved helper/example files to an assets directory (feel free to
  rearrange all of these again if you have any better ideas :D
- Renamed and moved tutorial file to make it more descriptive
- Removed old environment variables from post-receive hook example file
This commit is contained in:
m455 2022-12-20 00:42:35 -05:00
parent 031f975b2c
commit 907516d1d6
6 changed files with 233 additions and 177 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

148
README.md
View file

@ -1,33 +1,39 @@
# repo2html # 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)
- [Setting up a Git forge on your web server](#setting-up-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/), and 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) - [clojurian](https://wiki.call-cc.org/eggref/5/clojurian)
- [ersatz](https://wiki.call-cc.org/eggref/5/ersatz) - [ersatz](https://wiki.call-cc.org/eggref/5/ersatz)
- [lowdown](https://wiki.call-cc.org/eggref/5/lowdown) - [lowdown](https://wiki.call-cc.org/eggref/5/lowdown)
@ -38,46 +44,94 @@ no one is liable if this software breaks, deletes, corrupts, or ruins anything
- [sxml-transforms](https://wiki.call-cc.org/eggref/5/sxml-transforms) - [sxml-transforms](https://wiki.call-cc.org/eggref/5/sxml-transforms)
- [symbol-utils](https://wiki.call-cc.org/eggref/5/symbol-utils) - [symbol-utils](https://wiki.call-cc.org/eggref/5/symbol-utils)
- [utf8](https://wiki.call-cc.org/eggref/5/utf8) - [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 repository.
2. as root, run `make dependencies`
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/templates`, and you serve HTML files from `/var/www/git`, then you run `repo2html /var/www/git ~/bin/templates`.
### 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.
## Setting up a Git forge on your web server
Refer to [Create a Git forge with repo2html](documentation/create-a-git-forge-with-repo2html.md.html) to learn how use
`repo2html` as a post-receive hook to auto-generate HTML webpages for bare Git repositories on a remote web server.
## Alternative Git-to-HTML tools
- [stagit](https://codemadness.org/git/stagit/file/README.html) - [stagit](https://codemadness.org/git/stagit/file/README.html)
- [depp](https://git.8pit.net/depp.git/) - [depp](https://git.8pit.net/depp.git/)
- [git-arr](https://blitiri.com.ar/p/git-arr/) - [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

0
git-daemon.service → assets/git-daemon.service
View file

6
post-receive → assets/post-receive
View file

@ -6,10 +6,7 @@
# The toplevel path containing directories of static pages # The toplevel path containing directories of static pages
[ "$REPO2HTML_PREFIX" ] || export REPO2HTML_PREFIX=/var/www/git [ "$REPO2HTML_PREFIX" ] || export REPO2HTML_PREFIX=/var/www/git
# The toplevel clone url for repos. # 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_DESCRIPTION="sherry's git repositories"
export REPO2HTML_H1=git.example.com
# hueristic attempt to detect a reasonable default for the name of this repo # 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 # you may want to adjust this if you have e.g. sub-directories containing repos
@ -52,4 +49,5 @@ else
exit 1 exit 1
fi 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"

0
templates/default.html → assets/templates/default.html
View file

126
build-a-git-forge.md
View file

@ -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.

130
documentation/create-a-git-forge-with-repo2html.md Normal file
View file

@ -0,0 +1,130 @@
# Create a Git forge with repo2html
This tutorial teaches you how to use `repo2html` as a post-receive hook to
auto-generate HTML webpages for 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/default.html`
### 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`.