From 838489079e46f96175c90ddb94e503743c97a24e Mon Sep 17 00:00:00 2001 From: pho4cexa Date: Sun, 8 Jan 2023 00:53:04 -0800 Subject: [PATCH] attempt at consistent environment/git config --- README.md | 113 ++++++++++++++++++++++++++-------- assets/templates/default.html | 2 +- main.scm | 78 ++++++++++++----------- 3 files changed, 131 insertions(+), 62 deletions(-) diff --git a/README.md b/README.md index b910ec7..9c57477 100644 --- a/README.md +++ b/README.md @@ -80,27 +80,81 @@ into the `/usr/local/bin` directory. of compiling a static binary file, then run `cp main.scm /usr/local/bin/repo2html` as root. +## Templates + +You can customize `repo2html` by modifying the template file +`assets/templates/default.html`, and then specifying the directory containing +your modified `default.html` as the second command-line argument when running +`repo2html`. + +For example, if you placed a `default.html` template file in +`~/var/templates`, and you serve HTML files from `/var/www/git`, then you run +`repo2html /var/www/git ~/var/templates`. + +Templates are rendered using [ersatz](https://wiki.call-cc.org/eggref/5/ersatz), +whose syntax is similar to the [Jinja2](https://palletsprojects.com/p/jinja/) +templating system. + +If you use the `include` directive in your modified `default.html` template +file, `repo2html` will look for the templates to be included in that same +specified directory, where your `default.html` template lives. + ## Configuration -You can `repo2html` by changing the following items: +`repo2html` understands the following configuration settings. -- [Templates](#templates) -- [Environment variables](#environment-variables) +These settings are typically set using `git config` like -### Templates +```git config repo2html. value``` -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`. +Environment variables may also be used for configuration, and take precedence over settings in `git config`: -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`. +```export REPO2HTML_=value``` -### Environment variables +### Name -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. +- `$REPO2HTML_NAME` or +- `git config repo2html.name` +- default: the repo's directory name + +Your repository "name" is, by default, the name of the directory as specified in the first argument provided to `repo2html`. + +This affects the template variables: +This does not affect the template variables: + +### Description + +- `$REPO2HTML_DESCRIPTION` or +- `git config repo2html.description` or +- edit the `.git/description` file +- default: "" + +A short description for the repo. +This may also be set by adding a description in a `description` file in the root directory of your Git repository. +(This is the same mechanism that `cgit` uses.) + +### ForgeRoot + +- `$REPO2HTML_FORGEROOT` or +- `git config repo2html.forgeroot` + +This is a helper intended for use when [building a git forge](#creating-a-git-forge-on-your-web-server). + +It specifies the filesystem path to the directory containing (possibly a hierarchy of) html output directories. + +Example: + +With forgeroot unset, the command +`repo2html /var/www/repos/mike/projecta/repo1 /path/to/templates` +will set the variable repo_path to `repo1` + +With forgeroot set to `/var/www/repos`, the command +`repo2html /var/www/repos/mike/projecta/repo1 /path/to/templates` +will set the variable repo_path to `mike/projecta/repo1` + +When your forge is built with a shared git user, it's convenient to use --global to specify this just once, like: + +`sudo -u git git config --global repo2html.forgeroot /var/git-repos/` ## Creating a Git forge on your web server @@ -110,24 +164,19 @@ 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 +## Alternatives + +### Git Repo Static Page Generators + +Other tools like `repo2html`, that generate a set of HTML files representing the contents of a git repository. - [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 +### Git Forge Software -- [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/) -- [pagure](https://pagure.io/pagure) - -## Existing Git forge software +Software for self-hosting or building your own collection of many git repos for potentially multiple users. - [GitLab](https://about.gitlab.com/install/) - [Gogs](https://gogs.io/) @@ -138,8 +187,22 @@ push` to them. - [gitile](https://git.lepiller.eu/gitile) - [pagure](https://pagure.io/pagure) +### Git Forge Services + +Third-party-hosted services that will host browsable code repositories. + +- [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 +- [pagure](https://pagure.io/pagure) + ## Todos +- **documentation**: provide a precompiled binary download - **documentation/feature**: use post-update rather than post-receive hook for simplicity - **documentation**: also describe use with post-commit hook diff --git a/assets/templates/default.html b/assets/templates/default.html index 30999b2..9fe4f23 100644 --- a/assets/templates/default.html +++ b/assets/templates/default.html @@ -24,7 +24,7 @@

git.example.com

{{ repository_name }}

-

clone url: git://git.example.com/{{ repository_path }}

+

clone url: git://git.example.com{{ forge_url_path }}{{ repository_path }}