reporat

1 <img src="raw/reporat.png" alt="RepoRat with a wizard hat (and wand)" style="float: right;"> 2 3 # RepoRat 4 5 A static website generator for Git repos written in Ruby. 6 7 * Runs in milliseconds for small repos 8 * 'About' page displays truncated file list followed by formatted README 9 * 'Files' page lists all files with links to file pages 10 * 'Commits' page contains simple Git commit log 11 * Each human-readable source file has a viewing pages with linkable line numbers 12 * Displays common image formats inline 13 * Creates bare repo and link for "dumb http" Git cloning 14 * Does **not** create pages for individual commit changes, branches, etc. 15 16 ## Usage 17 18 Run RepoRat from the root directory of a Git repo. Example: 19 20 $ cd my_stuff/cool_repo 21 $ reporat.rb 22 RepoRat generating site for: 23 cool_repo 24 A really neat program. 25 Output complete at '/home/dave/my_repos/cool_repo' 26 27 For my own convenience, I've made a Bash function with my defaults: 28 29 $ type reporat 30 reporat is a function 31 reporat () 32 { 33 $HOME/proj/reporat/reporat.rb $1 $HOME/wiki/ratf/src/repos '../repos.css' 34 } 35 36 ## Configuration 37 38 There are enough parameters that taking them at the command line is unweildy. 39 40 Therefore, you are **required** to create a config at `~/.config/reporat.conf.rb`. 41 42 This is a pure Ruby source file with methods you define. 43 44 See the example file in this repo (which happens to be a copy of _my_ current 45 configuration): 46 47 <a href="html/reporat.conf.rb.html">reporat.conf.rb</a> 48 49 Note: Please allow RepoRat to create the individual repo directories underneath 50 the root output directory so it can determine if the repo is new or if it has 51 been processed before. 52 53 ## Bare repos and "dumb http" cloning 54 55 I've taken the unusual tactic of generating a new bare repo inside 56 the output directory when it is first created. Each time RepoRat 57 is re-run, the bare repo is re-synced with the latest changes and 58 the internals are updated to make it work as a clone source. 59 60 The bare repo is given the same name with `.git` appended as per convention: 61 62 cool_repo/cool_repo.git 63 64 Now the output directory is completely ready to be served as 65 static content over a Web server as-is. Git can clone your repo 66 from the bare repo path, discovering which files it needs to 67 create the clone. No server setup of any kind is needed! 68 69 ## Requirements 70 71 * Ruby 3.0 or higher 72 * Git (obviously?) 73 * <a href="https://www.pell.portland.or.us/~orc/Code/discount/">Discount</a>, a Markdown implementation in C by David Parsons. 74 75 **No gems** are used! Just the standard library that comes with Ruby. 76 77 ## Fast and personal software development 78 79 I've been keeping track of _exactly_ how long it takes me to work on this 80 program. I'm doing this because I've always been curious and also because it's 81 helping me stay focused and not waste my time on a lot of tangents. 82 83 I've got times in minutes here: 84 85 <a href="html/devlog.txt.html">devlog.txt</a> 86 87 Okay, this thing works pretty well and has all of the features I 88 need to begin with. Let's see how I've done: 89 90 $ ./time.rb 91 I've been at this for 614 minutes (about 10.2 hours). 92 93 And how big is it? 94 95 $ wc -l reporat.rb 96 317 reporat.rb 97 98 Seven days, mostly in the quiet morning time. Grand total of just 99 over **ten hours and 300 lines of Ruby**. Not bad! 100 101 This is currently specific to creating pages for my website, ratfactor.com, but 102 it should be trivial to change a couple paths and make it work for you! If you 103 have suggestions for generalizing this program, let me know. 104 105 ## Other static Git repo site generators 106 107 RepoRat was written for me. If it doesn't suit you, maybe one of these will: 108 109 * <a href="https://git.m455.casa/repo2html/">repo2html</a> by m455. RepoRat was directly inspired by this one. Written in Chicken Scheme (which generates C for compiling). 110 * <a href="https://codemadness.org/git/stagit/file/README.html">stagit</a> by Hiltjo Posthuma. Another direct inspiration for RepoRat. Written in C. 111 * <a href="https://git.8pit.net/depp/">depp</a> by Sören Tempel. The Motivation section of depp's readme nicely describes my own with RepoRat! Written in Go. 112 * <a href="https://blitiri.com.ar/p/git-arr/">git-arr</a> by Alberto Bertogli. Generates an entire site with all of your repos at once. Written in Python. 113 * <a href="https://git.mcksp.com/gituwa/">gituwa</a> by mcksp. Very nice-looking minimal static generator. Written in C. 114 115 ## License and what you can do with it 116 117 I'm releasing this under the GNU GPLv3 license. Please see the 118 <a href="html/LICENSE.html">LICENSE</a> text file in this repo. 119 120 In short, you can download, modify, and distribute this program. 121 122 In particular, it might be useful for generating custom pages for your website. 123 I'd love to hear about it if you do.