instructions on using git to edit pages
authorMichael Meffie <mmeffie@sinenomine.net>
Fri, 16 Nov 2012 15:45:56 +0000 (10:45 -0500)
committerMichael Meffie <mmeffie@sinenomine.net>
Fri, 16 Nov 2012 15:53:49 +0000 (10:53 -0500)
Thanks to Simon and Russ for setting up gerrit and openafs-wiki.git
for allowing git pushes to update the wiki.

Change-Id: Iab60f6103cff041abed535fa1db9c6b264c67066

GitWiki.mdwn [new file with mode: 0644]
index.mdwn

diff --git a/GitWiki.mdwn b/GitWiki.mdwn
new file mode 100644 (file)
index 0000000..9a19efd
--- /dev/null
@@ -0,0 +1,127 @@
+# Using git to edit the OpenAFS wiki
+
+This page describes how to use git to create and edit pages on the 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 it that you can edit while
+offline, and then submit your work later, as you would for any other git
+based version controlled files. 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.
+
+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, in addition to the
+wiki web based forms.
+
+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:
+
+* [[http://ikiwiki.info|ikiwiki]] installation
+* a basic ikiwiki setup file (shown below)
+* a basic web server to serve static files
+
+A database server is not required.
+
+## 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'.
+
+As described in [[GitDevelopers]], gerrit requires each commit to have a
+"change id" in the commit comment. The gerrit change id git hook should
+be downloaded from the [[OpenAFS]] gerrit server by running the
+following after running git clone,
+
+    scp -p -P 29418 gerrit.openafs.org:hooks/commit-msg openafs-wiki/.git/hooks/
+
+## 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 to allow you to preview your changes before
+committing them and pushing them to the wiki.  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.
+
+Install the ikiwiki package on your system. For example, to install ikiwiki on
+a recent Debian Linux:
+
+    sudo apt-get install ikiwiki
+
+Create a minimal ikiwiki configuration file by saving the following in
+the file '~/openafs-wiki.setup' (where &lt;username&gt; 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 => '',
+    }
+
+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
+
+Configure a web server running on your machine to resolve the 'url' to the
+'destdir'.  An example apache configuration:
+
+    Alias /openafs-wiki /home/<username>/public_html/openafs-wiki
+    <Directory /home/<username>/public_html/openafs-wiki>
+        Order allow,deny
+        allow from 127.0.0.1
+    </Directory>
+
+Be sure to reload apache after changing the configuration. The pages may be
+previewed by pointing a browser on your laptop at:
+
+    http://localhost/openafs-wiki/
+
+Regenerate the html files as changes are made to the source files
+with the 'ikiwiki' command:
+
+    ikiwiki --setup ~/openafs-wiki.setup --refresh
+
+## 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 'ikiwiki' command to refresh the html for preview. Use 'git
+add' and 'git commit' to create commits to be submitted.
+
+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, rather 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'.
+
index 2b6f9c1..14c3c22 100644 (file)
@@ -38,5 +38,7 @@ Welcome to the OpenAFS wiki. This is a web-based collaboration area for collecti
 ## About this wiki
 
 * [[How to use this wiki|ikiwiki]]
+* [[How to use git to edit pages|GitWiki]]
 * [[Orphaned pages|OrphanedPages]]
 
+