From 907516d1d687de8815d5856b081be5fa6f709e45 Mon Sep 17 00:00:00 2001 From: m455 Date: Tue, 20 Dec 2022 00:42:35 -0500 Subject: [PATCH 1/9] Updated documentation and cleaned up directory tree - 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 --- README.md | 148 ++++++++++++------ .../git-daemon.service | 0 post-receive => assets/post-receive | 6 +- {templates => assets/templates}/default.html | 0 build-a-git-forge.md | 126 --------------- .../create-a-git-forge-with-repo2html.md | 130 +++++++++++++++ 6 files changed, 233 insertions(+), 177 deletions(-) rename git-daemon.service => assets/git-daemon.service (100%) rename post-receive => assets/post-receive (91%) rename {templates => assets/templates}/default.html (100%) delete mode 100644 build-a-git-forge.md create mode 100644 documentation/create-a-git-forge-with-repo2html.md diff --git a/README.md b/README.md index d1bc96a..4b7ab60 100644 --- a/README.md +++ b/README.md @@ -1,33 +1,39 @@ # 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 ` + -run from a git repository, this command populates the directory `` 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. -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. -we describe how to use this technique to [build a static git forge](build-a-git-forge.md.html). +## Features -## 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 -- image support -- markdown files are rendered as html -- no resident background process +## Requirements -## disclaimer - -no one is liable if this software breaks, deletes, corrupts, or ruins anything - -## requirements - -- [chicken scheme](https://call-cc.org/), and eggs: +- [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 +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) - [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 -1. ensure you're in the repo2html git repository -2. as root, run `make dependencies` -3. run `make` -4. run `make install` as root +Run `repo2html` inside the root directory of a Git repository or a bare Git repository. -if you wish, you may then uninstall the chicken scheme compiler. +- `` is the path to the directory that you want the HTML files to be generated in. +- `` 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 -- **documenation**: scope the readme audience to folks who kind of know what they're doing with servers -- **documentation/feature**: use post-update rather than post-receive hook for simplicity -- **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 +**Note**: If you want to use `main.scm` as the `repo2html` executable, instead +of compiling a static binary file, then run +`cp main.scm /usr/local/bin/repo2html` as root. -## license: agpl-3.0+ +## Configuration -Copyright 2022 [Jesse Laprade](https://m455.casa). -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. +You can `repo2html` by changing the following items: -## 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) - [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 + diff --git a/git-daemon.service b/assets/git-daemon.service similarity index 100% rename from git-daemon.service rename to assets/git-daemon.service diff --git a/post-receive b/assets/post-receive similarity index 91% rename from post-receive rename to assets/post-receive index e400f5e..8e08257 100755 --- a/post-receive +++ b/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" diff --git a/templates/default.html b/assets/templates/default.html similarity index 100% rename from templates/default.html rename to assets/templates/default.html diff --git a/build-a-git-forge.md b/build-a-git-forge.md deleted file mode 100644 index ddc5b0a..0000000 --- a/build-a-git-forge.md +++ /dev/null @@ -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 `` 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. diff --git a/documentation/create-a-git-forge-with-repo2html.md b/documentation/create-a-git-forge-with-repo2html.md new file mode 100644 index 0000000..20ee280 --- /dev/null +++ b/documentation/create-a-git-forge-with-repo2html.md @@ -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`. + + From 7b5aab8a14ee202daeae5d5aa027ba165bb500b5 Mon Sep 17 00:00:00 2001 From: m455 <jesse@m455.casa> Date: Tue, 20 Dec 2022 00:58:11 -0500 Subject: [PATCH 2/9] fixed typo in docs --- README.md | 2 +- documentation/create-a-git-forge-with-repo2html.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 4b7ab60..381360a 100644 --- a/README.md +++ b/README.md @@ -86,7 +86,7 @@ You can `repo2html` by changing the following items: 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`. +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 diff --git a/documentation/create-a-git-forge-with-repo2html.md b/documentation/create-a-git-forge-with-repo2html.md index 20ee280..68be7b0 100644 --- a/documentation/create-a-git-forge-with-repo2html.md +++ b/documentation/create-a-git-forge-with-repo2html.md @@ -103,7 +103,7 @@ Ensure you're in the repo2html git repository, and follow the steps below: 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` + `path/to/directory/containing/template` to `~/bin` ### Enable cloning over git:// From 15aaf2bec4c251e4c1a2cc8c9759db9144d15b62 Mon Sep 17 00:00:00 2001 From: m455 <jesse@m455.casa> Date: Tue, 20 Dec 2022 01:01:32 -0500 Subject: [PATCH 3/9] more typos fixed --- README.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 381360a..fc0bcc6 100644 --- a/README.md +++ b/README.md @@ -115,12 +115,12 @@ Refer to [Create a Git forge with repo2html](documentation/create-a-git-forge-wi ## 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) +- [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 From ef34d55898db646379c22770531d05b1537ba70a Mon Sep 17 00:00:00 2001 From: m455 <jesse@m455.casa> Date: Tue, 20 Dec 2022 01:05:34 -0500 Subject: [PATCH 4/9] prefixed 'html/' to tutorial link. fixed line lengths --- README.md | 38 ++++++++++++++++++++++++++------------ 1 file changed, 26 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index fc0bcc6..10aa489 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # repo2html -A command-line tool that generates a static HTML representation of a Git repository. +A command-line tool that generates a static HTML representation of a Git +repository. ## Page contents @@ -50,9 +51,11 @@ A command-line tool that generates a static HTML representation of a Git reposit repo2html <destination> <template-directory> -Run `repo2html` inside the root directory of a Git repository or a bare Git repository. +Run `repo2html` inside the root directory of a Git repository or a bare Git +repository. -- `<destination>` is the path to the directory that you want the HTML files to be generated in. +- `<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. @@ -69,7 +72,8 @@ into the `/usr/local/bin` directory. 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. +4. As root, run `make install` to copy the `repo2html` binary into the + `/usr/local/bin` directory. **Note**: If you want to use `main.scm` as the `repo2html` executable, instead of compiling a static binary file, then run @@ -84,18 +88,25 @@ You can `repo2html` by changing the following items: ### 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`. +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`. +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. +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. +Refer to +[Create a Git forge with repo2html](html/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 @@ -124,14 +135,17 @@ Refer to [Create a Git forge with repo2html](documentation/create-a-git-forge-wi ## Todos -- **documentation/feature**: use post-update rather than post-receive hook for simplicity +- **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**: 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 +- **feature**: other mechanisms for header id application like uniqueness + checking, sequential numbering From b6097a77a5e9509a582edfb3739b8ee020697762 Mon Sep 17 00:00:00 2001 From: m455 <jesse@m455.casa> Date: Tue, 20 Dec 2022 01:07:47 -0500 Subject: [PATCH 5/9] hmm lets try to fix that link again... --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 10aa489..576c803 100644 --- a/README.md +++ b/README.md @@ -104,7 +104,7 @@ root directory of your Git repository. ## Setting up 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) +[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. From a063ba31faed018477611097c84779ee3f6efd9f Mon Sep 17 00:00:00 2001 From: m455 <jesse@m455.casa> Date: Tue, 20 Dec 2022 01:11:36 -0500 Subject: [PATCH 6/9] fixed a small nit in the requirements --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 576c803..fa9fc13 100644 --- a/README.md +++ b/README.md @@ -34,7 +34,8 @@ repository. ## Requirements -- [Chicken Scheme](https://call-cc.org/), and eggs: +- [Chicken Scheme](https://call-cc.org/) +- The following Chicken Scheme 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) From d210d06f8ff80357d578109c1aee1223669f9fd5 Mon Sep 17 00:00:00 2001 From: m455 <jesse@m455.casa> Date: Tue, 20 Dec 2022 01:22:38 -0500 Subject: [PATCH 7/9] small wording edit --- README.md | 9 +++++---- documentation/create-a-git-forge-with-repo2html.md | 6 +++--- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index fa9fc13..cee181c 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ repository. - [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) +- [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) @@ -102,12 +102,13 @@ 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 +## Creating 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. +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 diff --git a/documentation/create-a-git-forge-with-repo2html.md b/documentation/create-a-git-forge-with-repo2html.md index 68be7b0..9207c8b 100644 --- a/documentation/create-a-git-forge-with-repo2html.md +++ b/documentation/create-a-git-forge-with-repo2html.md @@ -1,8 +1,8 @@ # 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. +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 From d66ff630d20efff765115829ba0f09389317fcbb Mon Sep 17 00:00:00 2001 From: m455 <jesse@m455.casa> Date: Tue, 20 Dec 2022 01:27:22 -0500 Subject: [PATCH 8/9] hmm it doesn't work again lol --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index cee181c..337b1d6 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ root directory of your Git repository. ## Creating a Git forge on your web server Refer to -[Create a Git forge with repo2html](documentation/create-a-git-forge-with-repo2html.md.html) +[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. From 3656ea44471cf891cc5190797aa1c8cfdb2d66ed Mon Sep 17 00:00:00 2001 From: m455 <jesse@m455.casa> Date: Tue, 20 Dec 2022 01:36:28 -0500 Subject: [PATCH 9/9] small tutorial fix --- documentation/create-a-git-forge-with-repo2html.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/documentation/create-a-git-forge-with-repo2html.md b/documentation/create-a-git-forge-with-repo2html.md index 9207c8b..4ff7511 100644 --- a/documentation/create-a-git-forge-with-repo2html.md +++ b/documentation/create-a-git-forge-with-repo2html.md @@ -125,6 +125,8 @@ On your local machine, follow the steps below: 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`. +8. Navigate to `https://git.example.com/my-repository` in your browser. + +