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

attempt at consistent environment/git config

Browse source
This commit is contained in:
pho4cexa 2023-01-08 00:53:04 -08:00
parent 6f93a9d3b4
commit 838489079e
3 changed files with 131 additions and 62 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

113
README.md
View file

@ -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.<setting> 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_<SETTING>=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

2
assets/templates/default.html
View file

@ -24,7 +24,7 @@
<body>
<h1>git.example.com</h1>
<h2>{{ repository_name }}</h2>
<p>clone url: git://git.example.com/{{ repository_path }}</p>
<p>clone url: git://git.example.com{{ forge_url_path }}{{ repository_path }}</p>
<nav>
{% if readme_file %}
<a href="{{ relative_root }}{{ readme_file }}.html">about</a>

78
main.scm
View file

@ -187,6 +187,17 @@
(call-with-input-pipe read-lines)
(string-intersperse "\n")))
;; the result of asking git for some configuration; #f if no result.
(define (git-config->string key)
(let [(result (call-with-input-pipe (string-append "git config " key) read-line))]
(if (eof-object? result) #f result)))
;; environment always takes precedent over git-config
(define (config key)
(or
(get-environment-variable (string-append "REPO2HTML_" (string-upcase key)))
(git-config->string (string-append "repo2html." (string-downcase key)))))
;; sxml generators for constructed pages ---------------------------------
(define (source->sxml source-file) ;; src/main.scm
@ -296,49 +307,44 @@
;; git automatically updates this hash when you checkout/pull/etc.
(let* ((version-ident "$Id$")
(source-files-list (git-repository->paths-list))
(forge-root (string-append (string-chomp (or (config "forgeroot") "") "/") "/"))
;; should begin and end with "/"
(forge-url-path (string-append (string-chomp (or (config "forgeurlpath") "") "/") "/"))
(template-alist
`(;; variables provided to template at all times. beware: ersatz
;; templates break if you attempt to use a variable with a hyphen.
;; the list of all files in the git repo
(source_files_list . ,source-files-list)
;; the description of the repo, taken from env, falling back to
(forge_url_path . ,forge-url-path)
;; the description of the repo, taken from: env, config, cgit-like
;; description file
(repository_description
. ,(or (get-environment-variable "REPO2HTML_DESCRIPTION")
(if-let (f (file-exists? "description"))
(with-input-from-file f read-lines)
#f)
""))
;; the repository name, which we detect from the output directory
;; name. TODO: more heuristics if this doesn't work well
(repository_name
. ,(->
html-repo-path
(string-chomp "/")
(string-chomp ".git")
(pathname-strip-directory)))
;; the path from the URL root to the repository
(repository_path
. ,(->
html-repo-path
(string-chomp "/")
(pathname-strip-directory)))
;; the first README file found, if any.
(readme_file
. ,(find (cut member <> source-files-list)
'("README" "README.md" "README.txt")))
;; the first LICENSE file found, if any.
(license_file
. ,(find (cut member <> source-files-list)
'("LICENSE" "LICENSE.md" "LICENSE.txt")))
(repository_description . ,(or (config "description")
(if-let (f (file-exists? "description"))
(with-input-from-file f read-lines) #f)
""))
;; the name of the repo, which is usually but not necessarily the
;; same as its directory name (and last path element of the url)
(repository_name . ,(or (config "name")
(-> html-repo-path
(string-chomp ".git")
(pathname-strip-directory))))
;; the path from the forge root to the repository
(repository_path . ,(or (config "path")
(if (string-prefix? forge-root html-repo-path)
(string-drop html-repo-path (string-length forge-root))
(pathname-strip-directory html-repo-path))))
;; the first README file found among these, if any.
(readme_file . ,(find (cut member <> source-files-list)
'("README.md" "README" "README.txt")))
;; the first LICENSE file found among these, if any.
(license_file . ,(find (cut member <> source-files-list)
'("LICENSE.md" "LICENSE" "LICENSE.txt")))
;; the string "ISSUES" if any files exist in ISSUES/
(issues_file
. ,(and (find (cut string-prefix? "ISSUES/" <>) source-files-list) "ISSUES"))
(repo2html_version
. ,(if (equal? version-ident (list->string '(#\$ #\I #\d #\$)))
""
(substring* version-ident 5 12)))
(issues_file . ,(and (find (cut string-prefix? "ISSUES/" <>) source-files-list) "ISSUES"))
(repo2html_version . ,(if (equal? version-ident (list->string '(#\$ #\I #\d #\$)))
""
(substring* version-ident 5 12)))
))
(write-with-template
(make-template-writer-ersatz templates-directory template-alist)))
@ -401,6 +407,6 @@
(unless templates-directory
(bail "please specify the directory containing the templates.\nnote: built-in sxml templates have been removed."))
(generate-html-files html-repo-path templates-directory))
(generate-html-files (string-chomp html-repo-path "/") templates-directory))
(apply main (command-line-arguments))