gitit

After finding myself rather behind on a few different things I'm working on, I spent some time this weekend thinking about how to better order some of the things I'm doing. It seems this is a theme for 2011 so far, what with Plasma Active moving to iceScrum for project management and other similar events.

One thing that came to mind is that I'd could probably really use a personal wiki .. or three. Of course, I'm a picky sort of person and had all kinds of requirements in mind which I was fairly sure I wouldn't be able to find all in one tool. Essentially, I wanted something:

• similar enough to editing a Mediawiki-based wiki that it didn't feel too alien


• that can be set up in a matter of minutes


• that used git for storing the content so I could easily carry it with me on my laptop, but then sync it to a server somewhere without pain


• could host multiple wikis side-by-side

I search the Internet using variations on the search phrase "git wiki" (e.g. "git backed wiki") which gave me all kinds of results that had nothing to do with what I was looking for but, thankfully, also a small handful of links that were on target.

The first two options I found and tried left me feeling empty: they were featureless and not actively developed. Then I found gitit by John Macfarlane.

At first my heart sank: it was written in Haskell and looked to have some sort of arcane install process. That was just my ignorance speaking though, as I soon found that OpenSuse's warehouse of packages gave me quick access to everything needed to get gitit up and running. The most important bit was a tool called "cabal" that does all of the heavy lifting for you. After doing the "one-click" install of cabal (which ironically took more like a dozen clicks), it was installed and ready to run.

After adding the ~/.cabal/bin directory to my $PATH, I made a directory for the wiki content, ran `gitit --print-default-config > gitit.conf`, edited the config file (setting a title, changing the default port; it's very well documented) and then started the wiki with `gitit -f my-conf +RTS -I0 -RTS`. The latter bit of line-noise is to make Haskell behave nicely and not constantly run the garbage collector and thereby kill my laptop battery; I got this jewel from the gitit documentation which is very nicely written in my opinion. Creating a second wiki was as simple as reproducing those steps.

Best of all, going into the wikidata/ directory and doing things like `git log` gave me exactly what one would expect. It feels like a wiki via the web browser, but it's doing git magic in the back. Just like Plasmate does. Is this a part of the future of content-centric software?

I do miss templates from mediawiki, but other than that all is good: easy editing, page history, discussion pages, file uploads, user accounts, etc. It does lack a lot of features Mediawiki has, but I need none of them (save, perhaps, templates). It uses Markdown by default (though you can use various other markup styles, including something call "literate Haskell"), but can export to a myriad of formats including Mediawiki markup, HTML, LaTeX and what not. This part is all powered by another of John's projects: pandoc.

Performance wise it is instantaneous on the laptop (as one would expect) and does support things like caching pages and sitting behind a proxy web server. I haven't bothered to set up either feature as I don't need them, but how to do so is described clearly in the gitit documentation. The gitit process is currently taking ~8.5MB of resident memory and sharing another 25MB and idling, as one would hope, at 0% CPU usage so I have nothing to complain about there either.

I'm very happy to have found such a tool, all nicely GPL'd and everything, that performs like a champ and has absolutely zero lock-in thanks to the usage of things like git (for data management) and pandoc (for content format management). If you've been on the look-out for a similar tool, I heartily recommend checking gitit out.