attempt at consistent environment/git config

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)
+These settings are typically set using `git config` like
-- [Environment variables](#environment-variables)
 
-### Templates
+```git config repo2html.<setting> value```
 
-You can customize `repo2html` by editing the `assets/templates/default.html`,
+Environment variables may also be used for configuration, and take precedence over settings in `git config`:
-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
+```export REPO2HTML_<SETTING>=value```
-files from `/var/www/git`, then you run `repo2html /var/www/git ~/bin`.
 
-### Environment variables
+### Name
 
-You can provide a generic description by setting the `REPO2HTML_DESCRIPTION`
+- `$REPO2HTML_NAME` or
-environment variable, or by adding a description in a `description` file in the
+- `git config repo2html.name`
-root directory of your Git repository.
+- 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/)
+Software for self-hosting or building your own collection of many git repos for potentially multiple users.
-- [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
 
 - [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

assets/templates/default.html

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

main.scm

@@ -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
+            (repository_description . ,(or (config "description")
-             . ,(or (get-environment-variable "REPO2HTML_DESCRIPTION")
+                                           (if-let (f (file-exists? "description"))
-                    (if-let (f (file-exists? "description"))
+                                                   (with-input-from-file f read-lines) #f)
-                            (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)
-            ;; the repository name, which we detect from the output directory
+            (repository_name        . ,(or (config "name")
-            ;; name. TODO: more heuristics if this doesn't work well
+                                           (-> html-repo-path
-            (repository_name
+                                               (string-chomp ".git")
-             . ,(->
+                                               (pathname-strip-directory))))
-                 html-repo-path
+            ;; the path from the forge root to the repository
-                 (string-chomp "/")
+            (repository_path        . ,(or (config "path")
-                 (string-chomp ".git")
+                                           (if (string-prefix? forge-root html-repo-path)
-                 (pathname-strip-directory)))
+                                               (string-drop html-repo-path (string-length forge-root))
-            ;; the path from the URL root to the repository
+                                               (pathname-strip-directory html-repo-path))))
-            (repository_path
+            ;; the first README file found among these, if any.
-             . ,(->
+            (readme_file            . ,(find (cut member <> source-files-list)
-                 html-repo-path
+                                             '("README.md" "README" "README.txt")))
-                 (string-chomp "/")
+            ;; the first LICENSE file found among these, if any.
-                 (pathname-strip-directory)))
+            (license_file           . ,(find (cut member <> source-files-list)
-            ;; the first README file found, if any.
+                                             '("LICENSE.md" "LICENSE" "LICENSE.txt")))
-            (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")))
             ;; the string "ISSUES" if any files exist in ISSUES/
-            (issues_file
+            (issues_file            . ,(and (find (cut string-prefix? "ISSUES/" <>) source-files-list) "ISSUES"))
-             . ,(and (find (cut string-prefix? "ISSUES/" <>) source-files-list) "ISSUES"))
+            (repo2html_version      . ,(if (equal? version-ident (list->string '(#\$ #\I #\d #\$)))
-            (repo2html_version
+                                           ""
-             . ,(if (equal? version-ident (list->string '(#\$ #\I #\d #\$)))
+                                           (substring* version-ident 5 12)))
-                    ""
-                    (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))