diff --git a/README.md b/README.md index 75a3ca3..525cf2b 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,29 @@ # repo2html -a command-line tool that turns git repositories in html pages +**repo2html** generates static HTML pages for browsing the contents of a Git repository. + +## basic usage + +`repo2html DESTINATION` + +Assuming the current directory is a Git repository, this command populates *DESTINATION* with HTML files that provide a web-browsable view of the contents of the git repository. + +You may also cause this directory to be automatically updated upon every `git push`, by invoking *repo2html* as a Git *post-receive hook*. ## features - static html files -- image support (we're working on this) -- svg support (we're working on this) -- markdown files are rendered as html (we're working on this) -- no background process (unless you're using this tool as a post-receive hook, then you only need git-daemon running) -- default repository view is an html-rendered README.md file +- image support +- markdown files are rendered as html +- no resident background process ## caveats -- binary file contents are just... shown -- directory tree is shown as a flat list of files, so git repositories with - many files and directories will look awful -- no commit log (yet?) -- no line numbers (yet?) +- need better detection and rendering of binary files +- directory tree is shown as a flat list of files +- no commit log yet +- no line numbers yet +- no customizable templates yet ## disclaimer @@ -25,16 +31,13 @@ no one is liable if this software breaks, deletes, corrupts, or ruins anything ## requirements -- [chicken scheme](https://call-cc.org/) -- [utf8 egg](https://wiki.call-cc.org/eggref/5/utf8) -- [lowdown egg](https://wiki.call-cc.org/eggref/5/lowdown) -- [sxml-transforms egg](https://wiki.call-cc.org/eggref/5/sxml-transforms) -- [clojurian egg](https://wiki.call-cc.org/eggref/5/clojurian) +- [chicken scheme](https://call-cc.org/), and eggs: + - [utf8](https://wiki.call-cc.org/eggref/5/utf8) + - [lowdown](https://wiki.call-cc.org/eggref/5/lowdown) + - [sxml-transforms](https://wiki.call-cc.org/eggref/5/sxml-transforms) + - [clojurian](https://wiki.call-cc.org/eggref/5/clojurian) - git -**note**: if you have chicken scheme installed, then you can install the eggs -above by running `make dependencies` as root. - ## quickstart 1. ensure you've set up a web directory and have replaced the @@ -154,11 +157,24 @@ TODO - **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 -- **feature** : if no README.md file exists in the root directory of the repository, then don't create the "about" nav link. instead, make the files page the index.html -- **feature**: add a "license" nav link if a LICENSE file exists in the root directory of the repository. if no LICENSE file exists, then don't create the "license" nav link ## hopes - **feature**: clickable line numbers in source files - **feature**: make repos with more files and directories less daunting (recursively generate a files list page for each directory in a repo?) -- **feature**: nav link: Releases +- **feature**: nav links: Releases, Branches, Commits (Log) + +## should we...? + +- **feature**: display binary files as output from binary-file analysis tools like hexdump, xxd, dumpelf, elfls, readelf, etc.? + +## license: agpl-3.0+ + +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. + +## alternatives + +- [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/) diff --git a/main.scm b/main.scm index 4ba54dd..3baf4ae 100755 --- a/main.scm +++ b/main.scm @@ -75,8 +75,15 @@ hr {

#{repository-name}

clone url: #{CLONE-URL}/#{repository-name}

@@ -160,6 +167,11 @@ string-block `(li ,author))) (call-with-input-pipe "git shortlog -ns HEAD" read-lines)))))) +(define (first-if pred lst) + (cond ((null? lst) #f) + ((pred (car lst)) (car lst)) + (else (first-if pred (cdr lst))))) + (define (generate-html-files html-repo-path) (let ((source-files-list (git-repository->paths-list)) (repository-name (pathname-strip-directory (string-chomp html-repo-path "/")))) @@ -172,10 +184,10 @@ string-block (lambda () (populate-html-template repository-name filename display-body-thunk)))) (create-directory html-repo-path #t) - - (write-with-template "index.html" (lambda () (display-readme-html))) + ;; special files (write-with-template "files.html" (lambda () (display-files-html source-files-list))) - (write-with-template "contributors.html" (lambda () (display-contributors-html))) + (write-with-template "contributors.html" display-contributors-html) + ;; htmlified repo contents (for-each (lambda (source-file) (write-with-template @@ -186,7 +198,16 @@ string-block (system (format "git show HEAD:~a > ~a" source-file (make-pathname html-repo-path source-file)))))) - source-files-list))) + source-files-list) + ;; if README exists copy it to index.html. otherwise copy files.html to + ;; index.html. + (copy-file + (first-if + file-exists? + (map (lambda (x) (make-pathname html-repo-path x)) + '("README.md.html" "README.html" "README.txt.html" "files.html"))) + (make-pathname html-repo-path "index.html") + #t))) (define (bail . args) (let-optionals args ((status 1) (msg ""))