# 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. Also, 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.
Read [[GitDevelopers]] before following the instructions on this page.
## Prerequisites
The following are needed to be able to edit the wiki pages with git.
* git installed and configured with your name and email.
* an OpenAFS gerrit account; see [[registering with gerrit|GitDevelopers]] for details.
A installation of the ikiwiki software on your laptop or workstation is
recommended so you can preview your changes before submitting them to the
OpenAFS wiki. This requires:
* [[ikiwiki|http://ikiwiki.info]] installation
* a basic ikiwiki setup file (shown below)
* a browser
## Getting the wiki source pages
Use 'git clone' to get the openafs-wiki source files:
git clone git://git.openafs.org/openafs-wiki.git
This will clone the wiki git repository to a new directory called
'openafs-wiki'.
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.
## Setting up ikiwiki to preview your changes
This is an optional but recommended step. The ikiwiki software can be installed
on your laptop or workstation so you can preview your changes before publishing
them. The default ikiwiki installation is intended for a server setup, so
users to create pages using the web-based CGI program. In this section, a
simplified setup is shown, which avoids some of the complexity of the ikiwiki
setup but allows you to preview changes made to the wiki source files.
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|http://ikiwiki.info/download]] for installation
instructions for other various 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//openafs-wiki',
destdir => '/home//public_html/openafs-wiki',
url => 'http://localhost/openafs-wiki/',
rcs => '',
usedirs => 0,
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. 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
The pages may be previewed locally by pointing your browser at:
file:///home//public_html/openafs-wiki/index.html
## Editing pages
You can now use your favorite text editor to change the markdown source and to
create new markdown files. When creating new files, be sure to create new links
on existing pages so visitors will be able to navigate to your
new page. Run the following `ikiwiki` command to regenerate the html files from
the source files.
ikiwiki --setup ~/openafs-wiki.setup --refresh
To preview a page, point your browser at:
file:///home//public_html/openafs-wiki/.html
When you are satified with your changes, use `git add` and `git commit` to
create a commit to be submitted, then to publish your changes on the wiki, push
your commits directly to the 'master' branch of the openafs-wiki.git repository
on gerrit.
git push ssh://gerrit.openafs.org/openafs-wiki.git HEAD:refs/heads/master
The changes will not be held by gerrit for review. The commit will be merged
immediately to the openafs-wiki.git repository and the html on the wiki server
will be automatically updated after a successful 'git push'.