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.

Setup

Read GitDevelopers before following the instructions on this page.

Create an OpenAFS gerrit account if you do not already have one. See registering with gerrit for details.

Install git on your system.

Set up your OpenSSH configuration to connect to the gerrit server as described in GitDevelopers. Do not set up the commit hook to generate gerrit change numbers in commit messages. Gerrit change ids are not used in the wiki pages.

Host gerrit.openafs.org
  User <username>
  IdentityFile ~/.ssh/<ident>
  Port 29418
  HostKeyAlgorithms +ssh-rsa
  PubkeyAcceptedAlgorithms +ssh-rsa

Getting the wiki source

Use git clone to get the openafs-wiki source files:

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

WARNING: Do not use the mirror on git.openafs.org or your pushes will fail.

Local preview (optional)

This step is optional, but recommended. It is possible to install the ikiwiki software locally to allow you to preview your changes before pushing them.

Debian/Ubuntu

$ sudo apt install make ikiwiki python3 xdg-utils

Fedora

$ sudo yum install make ikiwiki python3 xdg-utils

For other platforms, you may need to install ikiwiki from source. See https://ikiwiki.info/install for instructions.

A makefile is provided for a previewing your local changes in your browser to let you check your changes before doing a git push. Run make preview in the top-level directory to generate the html and preview the wiki in a browser:

$ make preview
(Press <control>-c to exit.)

Run make clean to cleanup the files created after a preview.

$ make clean

Pushing changes

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 of gerrit.openafs.org/openafs-wiki.git. 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.