+++ /dev/null
-# 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 ssh://gerrit.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.
-
-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.
-
-## 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|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/<username>/openafs-wiki',
- destdir => '/home/<username>/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/<username>/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/<username>/public_html/openafs-wiki/<NameOfPage>.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'.
git://git.openafs.org / openafs-wiki.git / blobdiff