RepoRat

A static website generator for Git repos written in Ruby.

Runs in milliseconds for small repos
‘About’ page displays truncated file list followed by formatted README
‘Files’ page lists all files with links to file pages
‘Commits’ page contains simple Git commit log
Each human-readable source file has a viewing pages with linkable line numbers
Displays common image formats inline
Creates bare repo and link for “dumb http” Git cloning
Does not create pages for individual commit changes, branches, etc.

Usage

Run RepoRat from the root directory of a Git repo. Example:

$ cd my_stuff/cool_repo
$ reporat.rb
RepoRat generating site for:
    cool_repo
    A really neat program.
Output complete at '/home/dave/my_repos/cool_repo'

For my own convenience, I’ve made a Bash function with my defaults:

$ type reporat
reporat is a function
reporat () 
{ 
    $HOME/proj/reporat/reporat.rb $1 $HOME/wiki/ratf/src/repos '../repos.css'
}

Configuration

There are enough parameters that taking them at the command line is unweildy.

Therefore, you are required to create a config at ~/.config/reporat.conf.rb.

This is a pure Ruby source file with methods you define.

See the example file in this repo (which happens to be a copy of my current configuration):

reporat.conf.rb

Note: Please allow RepoRat to create the individual repo directories underneath the root output directory so it can determine if the repo is new or if it has been processed before.

Bare repos and “dumb http” cloning

I’ve taken the unusual tactic of generating a new bare repo inside the output directory when it is first created. Each time RepoRat is re-run, the bare repo is re-synced with the latest changes and the internals are updated to make it work as a clone source.

The bare repo is given the same name with .git appended as per convention:

cool_repo/cool_repo.git

Now the output directory is completely ready to be served as static content over a Web server as-is. Git can clone your repo from the bare repo path, discovering which files it needs to create the clone. No server setup of any kind is needed!

Requirements

Ruby 3.0 or higher
Git (obviously?)
Discount, a Markdown implementation in C by David Parsons.

No gems are used! Just the standard library that comes with Ruby.

Fast and personal software development

I’ve been keeping track of exactly how long it takes me to work on this program. I’m doing this because I’ve always been curious and also because it’s helping me stay focused and not waste my time on a lot of tangents.

I’ve got times in minutes here:

devlog.txt

Okay, this thing works pretty well and has all of the features I need to begin with. Let’s see how I’ve done:

$ ./time.rb
I've been at this for 614 minutes (about 10.2 hours).

And how big is it?

$ wc -l reporat.rb
317 reporat.rb

Seven days, mostly in the quiet morning time. Grand total of just over ten hours and 300 lines of Ruby. Not bad!

This is currently specific to creating pages for my website, ratfactor.com, but it should be trivial to change a couple paths and make it work for you! If you have suggestions for generalizing this program, let me know.

Other static Git repo site generators

RepoRat was written for me. If it doesn’t suit you, maybe one of these will:

repo2html by m455. RepoRat was directly inspired by this one. Written in Chicken Scheme (which generates C for compiling).
stagit by Hiltjo Posthuma. Another direct inspiration for RepoRat. Written in C.
depp by Sören Tempel. The Motivation section of depp’s readme nicely describes my own with RepoRat! Written in Go.
git-arr by Alberto Bertogli. Generates an entire site with all of your repos at once. Written in Python.
gituwa by mcksp. Very nice-looking minimal static generator. Written in C.

License and what you can do with it

I’m releasing this under the GNU GPLv3 license. Please see the LICENSE text file in this repo.

In short, you can download, modify, and distribute this program.

In particular, it might be useful for generating custom pages for your website. I’d love to hear about it if you do.

Files