This week's Git Tip of the Week is slightly off topic, talking about the Git-based wiki Gollum. You can subscribe to the feed if you want to receive new instalments automatically.
Wikis
Wikis have been around with us for over 15 years, and being able to edit a page from any location has been a massive timesaver in documentation generation. Most of the EGit User guide has been created through the use of wiki contributions.
One problem with most wikis is that you need to be on-line in order to interact with them. (There are some clients that cache pages from Wikipedia for off-line reading, but these are not able to manage changes.) Wouldn't it be great if we could have a system that allowed us to edit wikis off-line, and merge our changes back in when we are connected again?
Gollum
Enter Gollum from those fine people at GitHub. This is a ruby implemented wiki server which allows you to view, edit and save documents into a wiki on your local machine. (It's been around for a while but not widely known about, for some reason.)
As it's from GitHub (and this post is about Git tips, after all) then it should come as no surprise that Gollum is a wiki server for wiki pages backed by a git repository. Each save corresponds to an individual commit in the repository, and the “write a change message” box at the bottom is translated to the Git commit message.
Each wiki page is translated to a page specified in the --page-file-dir directory (or the repository root, if not set). Furthermore, the markup is user-configurable and defaults based on extension type (the default for new pages is Markdown). Other sane wiki formats (like MediaWiki) are also supported, though insane formats (like confluence) are not. In fact, the multi-wiki-format is supported through Jekyll, so whatever formats are supported there are likely to be usable.
Up and running
Installing Gollum is easy, provided you have Ruby installed (which you do if you have OSX). You can run:
sudo gem install gollum
… which will install it in your system's path automatically, or without sudo to install in a per-user path (which on OSX is in ~/.gem/ruby/1.8/bin, which you'll have to add to your path if you want to run it from the command line).
Once installed, you can create a repository, fire up Gollum, open a web browser, and you're off:
git init TestWiki gollum --page-file-dir wiki TestWiki openurl http://localhost:4567
This creates a new wiki (for test purposes) and fires up the Gollum server, pointing it to that Git repository. We have specified wiki as the subdirectory, so that when we commit a file, we're writing it into TestWiki/wiki/PageName.md.
Formats
There are many different types of formats that are supported by Gollum, but the parsers have to be installed separately in order to see any wiki content rendered as you expect.
- Markdown
gem install rdiscount - MediaWiki
gem install wikicloth
If you want to pretty-print code, you can use Pygments with sudo easy_install pygments. This allows you to begin code with ```java and end with ``` to pretty-print the embedded code snippet.
So, if you try editing a page and the markup isn't being rendered appropriately, check that you have the appropriate renderer installed in order to work.
Identity
Git commits in the repository use the credentials that are associated with the user who launched Gollum. Whilst this works for open projects, if you want to have a recorded user from some kind of SSO, you'll need to integrate this. Gollum uses the Ruby Sinatra to generate the web-based front end, and this is used to determine whether authentication is used or not (see the FAQ).
However, it doesn't support passthrough of the committer's identity into the commits, or using the GIT_AUTHOR_EMAIL or GIT_COMMITTER_EMAIL variables (though this is an issue with Grit, the Ruby front-end to the Git repository). This, combined with lack of multi-project support somewhat limits it for production uses, but works fine for a local (single user) wiki.
Summary
Gollum provides a powerful web-based mechanism to edit wiki pages in a local git repository, using the local user's commit credentials. This allows a distributed wiki to be edited remotely (whilst disconnected) but managed by Git under the covers, including the ability to branch, tag, and distributed pushing.
Whilst it's lacking in some key use cases that make a distributed wiki front end for teams of users, for an anonymous wiki (or one where the committer credentials are of lesser importance) it's an incredibly easy system to get up and running. And for those that regularly write whilst disconnected, it can be a good way to build up a repository of information without needing to be connected yet still allow those changes to be merged into a repository when reconnected.
Come back next week for another instalment in the Git Tip of the Week series.