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. 19 20 Example: 21 22 $ cd my_stuff/cool_repo 23 $ reporat.rb 24 RepoRat generating site for: 25 cool_repo 26 A really neat program. 27 Output complete at '/home/dave/my_repos/cool_repo' 28 29 ## Configuration 30 31 There are enough parameters that taking them at the command line is unweildy. 32 33 Therefore, you are **required** to create a config at `~/.config/reporat.conf.rb`. 34 35 This is a pure Ruby source file with methods you define. 36 37 See the example file in this repo (which happens to be a copy of _my_ current 38 configuration): 39 40 <a href="html/reporat.conf.rb.html">reporat.conf.rb</a> 41 42 Note: Please allow RepoRat to create the individual repo directories underneath 43 the root output directory so it can determine if the repo is new or if it has 44 been processed before. 45 46 ## Bare repos and "dumb http" cloning 47 48 I've taken the unusual tactic of generating a new bare repo inside 49 the output directory when it is first created. Each time RepoRat 50 is re-run, the bare repo is re-synced with the latest changes and 51 the internals are updated to make it work as a clone source. 52 53 The bare repo is given the same name with `.git` appended as per convention: 54 55 cool_repo/cool_repo.git 56 57 Now the output directory is completely ready to be served as 58 static content over a Web server as-is. Git can clone your repo 59 from the bare repo path, discovering which files it needs to 60 create the clone. No server setup of any kind is needed! 61 62 ## Requirements 63 64 * Ruby 3.0 or higher 65 * Git (obviously?) 66 * <a href="https://www.pell.portland.or.us/~orc/Code/discount/">Discount</a>, a Markdown implementation in C by David Parsons. 67 68 **No gems** are used! Just the standard library that comes with Ruby. 69 70 ## Fast and personal software development 71 72 I've been keeping track of _exactly_ how long it takes me to work on this 73 program. I'm doing this because I've always been curious and also because it's 74 helping me stay focused and not waste my time on a lot of tangents. 75 76 I've got times in minutes here: 77 78 <a href="html/devlog.txt.html">devlog.txt</a> 79 80 Okay, this thing works pretty well and has all of the features I 81 need to begin with. Let's see how I've done: 82 83 $ ./time.rb 84 I've been at this for 614 minutes (about 10.2 hours). 85 86 And how big is it? 87 88 $ wc -l reporat.rb 89 317 reporat.rb 90 91 Seven days, mostly in the quiet morning time. Grand total of just 92 over **ten hours and 300 lines of Ruby**. Not bad! 93 94 This is currently specific to creating pages for my website, ratfactor.com, but 95 it should be trivial to change a couple paths and make it work for you! If you 96 have suggestions for generalizing this program, let me know. 97 98 ## Other static Git repo site generators 99 100 RepoRat was written for me. If it doesn't suit you, maybe one of these will: 101 102 * <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). 103 * <a href="https://codemadness.org/git/stagit/file/README.html">stagit</a> by Hiltjo Posthuma. Another direct inspiration for RepoRat. Written in C. 104 * <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. 105 * <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. 106 * <a href="https://git.mcksp.com/gituwa/">gituwa</a> by mcksp. Very nice-looking minimal static generator. Written in C. 107 108 ## License and what you can do with it 109 110 I'm releasing this under the GNU GPLv3 license. Please see the 111 <a href="html/LICENSE.html">LICENSE</a> text file in this repo. 112 113 In short, you can download, modify, and distribute this program. 114 115 In particular, it might be useful for generating custom pages for your website. 116 I'd love to hear about it if you do.