Using git to edit the OpenAFS wiki

Unlike most wiki engines, which generate html from database records, the wiki engine on the OpenAFS wiki site generates static html files from a set of source files in markdown format. Revision history of the pages is managed with git. The OpenAFS gerrit system has been configured to accept git pushes to update the wiki, which means it is now possible to update this site using git directly.

This page describes how to use git to create and edit pages on this wiki as an alternative to the online web form. A local wiki setup is described to allow you to preview changes before pushing them to the public wiki. One advantage to this approach is that you can edit while offline and then submit your work later, as you would for any other git based project. Using git for making changes is especially handy when making a series of changes which should be committed together, such as reorganizing pages and links.

Prerequisites

Read GitDevelopers before following the instructions on this page.

The following are needed to be able to edit the wiki pages with git.

git is installed and configured with your name and email.
an OpenAFS gerrit account; see registering with gerrit for details.

A installation of the ikiwiki software on your laptop or workstation is recommended but is optional. This will allow you preview your changes before submitting them to the OpenAFS wiki. The ikiwiki requires:

ikiwiki installation
a basic ikiwiki setup file (shown below)
a basic httpd setup

Getting the wiki source pages

Use git clone to get the openafs-wiki source files from the gerrit.openafs.org repo.

git clone ssh://gerrit.openafs.org/openafs-wiki.git

Set up your OpenSSH configuration to connect to the gerrit server port as described in GitDevelopers. The commit hook which generates a gerrit 'change id' as described in GitDevelopers is not required for pushing openafs-wiki changes to gerrit.

Note: At this time, the git.openafs.org repo (gitweb) can trail the canonical repo on gerrit.openafs.org, since changes made through the web interface are not automatically propagated to the openafs gitweb. This means that if you want to make changes by pulling and pushing via git, you must pull from the gerrit.openafs.org repository above. If you pull from git.openafs.org, subsequent pushing may fail.

Editing pages

When you are satisfied with your changes, use git add and git commit to create a commit to be submitted. To publish your changes on the wiki, push your commits directly to the master branch master. Do not push to the gerrit review branch refs/for/master.

git push origin master

The commit will be merged immediately to the openafs-wiki.git repository. The html on the wiki server will be automatically updated after a successful git push after a few moments. The changes will not be held by gerrit for review.

Setting up ikiwiki to preview your changes

This is an optional but recommended step. The ikiwiki software can be installed on your local machine so you can preview your changes before publishing them on the wiki. The default ikiwiki installation instructions are intended for a server setup. A simplified, minimal setup is shown here.

First, install the ikiwiki package for your system. Use apt to install ikiwiki on a Debian or Ubuntu system.

sudo apt-get install ikiwiki

See ikiwiki downloads for installation instructions for other platforms.

Create a minimal ikiwiki configuration file by saving the following in the file '~/openafs-wiki.setup', where <username> is your username:

use IkiWiki::Setup::Standard {
    wikiname => 'openafs-wiki',
    srcdir => '/home/<username>/openafs-wiki',
    destdir => '/home/<username>/public_html/openafs-wiki',
    url => 'http://localhost/openafs-wiki/',
    rcs => '',
    usedirs => 1,
    add_plugins => [qw{goodstuff}],
}

The 'srcdir' should reference your local openafs-wiki git repository, created by the git clone. The 'destdir' will be created by ikiwiki when the pages are generated for preview. The 'destdir' may be set to a DocumentRoot directory if you have a local http server to show the pages.

Note the 'rcs' setting is intentionally left empty in this setup.

The html files can now be generated from the openafs-wiki source by 'ikiwiki'. Run the following command to create the 'destdir' directory and create the static html files in that directory:

ikiwiki --setup ~/openafs-wiki.setup

Install a httpd server, such as apache. Configure the document root to be the same as the destdir path in the openafs-wiki.setup file.

The pages may be previewed locally by pointing your browser at:

http://localhost/

Run the following ikiwiki command to regenerate the html files from the source files after making any changes to the source files.

ikiwiki --setup ~/openafs-wiki.setup --refresh