GitWiki.mdwn

   1 # Using git to edit the OpenAFS wiki
   2
   3 This page describes how to use git to create and edit pages on the this
   4 wiki as an alternative to the online web form. A local wiki setup is
   5 described to allow you to preview changes before pushing them to the
   6 public wiki. One advantage to this approach it that you can edit while
   7 offline, and then submit your work later, as you would for any other git
   8 based version controlled files. Also, using git for making changes is
   9 especially handy when making a series of changes which should be
  10 committed together, such as reorganizing pages and links.
  11
  12 Unlike most wiki engines, which generate html from database records,
  13 the wiki engine on the OpenAFS wiki site generates static html files
  14 from a set of source files in markdown format. Revision history of the
  15 pages is managed with git. The OpenAFS gerrit system has been
  16 configured to accept git pushes to update the wiki, which means it is
  17 now possible to update this site using git directly, in addition to the
  18 wiki web based forms.
  19
  20 Read [[GitDevelopers]] before following the instructions on this page.
  21
  22 ## Prerequisites
  23
  24 The following are needed to be able to edit the wiki pages with git.
  25
  26 * git installed and configured with your name and email.
  27 * an OpenAFS gerrit account; see [[registering with gerrit|GitDevelopers]] for details.
  28
  29 A installation of the ikiwiki software on your laptop or workstation is
  30 recommended so you can preview your changes before submitting them to the
  31 OpenAFS wiki. This requires:
  32
  33 * [[ikiwiki|http://ikiwiki.info]] installation
  34 * a basic ikiwiki setup file (shown below)
  35 * a basic web server to serve static files
  36
  37 A database server is not required.
  38
  39 ## Getting the wiki source pages
  40
  41 Use 'git clone' to get the openafs-wiki source files:
  42
  43     git clone git://git.openafs.org/openafs-wiki.git
  44
  45 This will clone the wiki git repository to a new directory called
  46 'openafs-wiki'.
  47
  48 The commit hook which generates a gerrit 'change id' as described in
  49 [[GitDevelopers]] is not required for pushing openafs-wiki changes to gerrit.
  50
  51 ## Setting up ikiwiki to preview your changes
  52
  53 This is an optional but recommended step. The ikiwiki software can be installed
  54 on your laptop or workstation to allow you to preview your changes before
  55 committing them and pushing them to the wiki.  The default ikiwiki installation
  56 is intended for a server setup, so users to create pages using the web-based
  57 CGI program. In this section, a simplified setup is shown, which avoids some of
  58 the complexity of the ikiwiki setup but allows you to preview changes made to
  59 the wiki source files.
  60
  61 Install the ikiwiki package on your system. For example, to install ikiwiki on
  62 a recent Debian Linux:
  63
  64     sudo apt-get install ikiwiki
  65
  66 Create a minimal ikiwiki configuration file by saving the following in
  67 the file '~/openafs-wiki.setup' (where &lt;username&gt; is your username)
  68
  69     use IkiWiki::Setup::Standard {
  70         wikiname => 'openafs-wiki',
  71         srcdir => '/home/<username>/openafs-wiki',
  72         destdir => '/home/<username>/public_html/openafs-wiki',
  73         url => 'http://localhost/openafs-wiki/',
  74         rcs => '',
  75     }
  76
  77 The 'srcdir' should reference your local openafs-wiki git repository,
  78 created by the git clone. The 'destdir' will be created by ikiwiki when
  79 the pages are generated for preview. Note the 'rcs' setting is
  80 intentionally left empty in this setup.
  81
  82 The html files can now be generated from the openafs-wiki source by 'ikiwiki'.
  83 Run the following command to create the 'destdir' directory and create the
  84 static html files in that directory:
  85
  86     ikiwiki --setup ~/openafs-wiki.setup
  87
  88 Configure a web server running on your machine to resolve the 'url' to the
  89 'destdir'.  An example apache configuration:
  90
  91     Alias /openafs-wiki /home/<username>/public_html/openafs-wiki
  92     <Directory /home/<username>/public_html/openafs-wiki>
  93         Order allow,deny
  94         allow from 127.0.0.1
  95     </Directory>
  96
  97 Be sure to reload apache after changing the configuration. The pages may be
  98 previewed by pointing a browser on your laptop at:
  99
 100     http://localhost/openafs-wiki/
 101
 102 Regenerate the html files as changes are made to the source files
 103 with the 'ikiwiki' command:
 104
 105     ikiwiki --setup ~/openafs-wiki.setup --refresh
 106
 107 ## Editing pages
 108
 109 You can now use your favorite text editor to change the markdown source and to
 110 create new markdown files. When creating new files, be sure to create new links
 111 on existing pages so visitors will be able to navigate to your
 112 new page. Run the 'ikiwiki' command to refresh the html for preview. Use 'git
 113 add' and 'git commit' to create commits to be submitted.
 114
 115 To publish your changes on the wiki, push your commits directly to the
 116 'master' branch of the openafs-wiki.git repository on gerrit.
 117
 118     git push ssh://gerrit.openafs.org/openafs-wiki.git HEAD:refs/heads/master
 119
 120 The changes will not be held by gerrit for review, rather will be merged
 121 immediately to the openafs-wiki.git repository. The html on the wiki
 122 server will be automatically updated after a successful 'git push'.
 123