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 As described in [[GitDevelopers]], gerrit requires each commit to have a
  49 "change id" in the commit comment. The gerrit change id git hook should
  50 be downloaded from the [[OpenAFS]] gerrit server by running the
  51 following after running git clone,
  52
  53     scp -p -P 29418 gerrit.openafs.org:hooks/commit-msg openafs-wiki/.git/hooks/
  54
  55 ## Setting up ikiwiki to preview your changes
  56
  57 This is an optional but recommended step. The ikiwiki software can be installed
  58 on your laptop or workstation to allow you to preview your changes before
  59 committing them and pushing them to the wiki.  The default ikiwiki installation
  60 is intended for a server setup, so users to create pages using the web-based
  61 CGI program. In this section, a simplified setup is shown, which avoids some of
  62 the complexity of the ikiwiki setup but allows you to preview changes made to
  63 the wiki source files.
  64
  65 Install the ikiwiki package on your system. For example, to install ikiwiki on
  66 a recent Debian Linux:
  67
  68     sudo apt-get install ikiwiki
  69
  70 Create a minimal ikiwiki configuration file by saving the following in
  71 the file '~/openafs-wiki.setup' (where &lt;username&gt; is your username)
  72
  73     use IkiWiki::Setup::Standard {
  74         wikiname => 'openafs-wiki',
  75         srcdir => '/home/<username>/openafs-wiki',
  76         destdir => '/home/<username>/public_html/openafs-wiki',
  77         url => 'http://localhost/openafs-wiki/',
  78         rcs => '',
  79     }
  80
  81 The 'srcdir' should reference your local openafs-wiki git repository,
  82 created by the git clone. The 'destdir' will be created by ikiwiki when
  83 the pages are generated for preview. Note the 'rcs' setting is
  84 intentionally left empty in this setup.
  85
  86 The html files can now be generated from the openafs-wiki source by 'ikiwiki'.
  87 Run the following command to create the 'destdir' directory and create the
  88 static html files in that directory:
  89
  90     ikiwiki --setup ~/openafs-wiki.setup
  91
  92 Configure a web server running on your machine to resolve the 'url' to the
  93 'destdir'.  An example apache configuration:
  94
  95     Alias /openafs-wiki /home/<username>/public_html/openafs-wiki
  96     <Directory /home/<username>/public_html/openafs-wiki>
  97         Order allow,deny
  98         allow from 127.0.0.1
  99     </Directory>
 100
 101 Be sure to reload apache after changing the configuration. The pages may be
 102 previewed by pointing a browser on your laptop at:
 103
 104     http://localhost/openafs-wiki/
 105
 106 Regenerate the html files as changes are made to the source files
 107 with the 'ikiwiki' command:
 108
 109     ikiwiki --setup ~/openafs-wiki.setup --refresh
 110
 111 ## Editing pages
 112
 113 You can now use your favorite text editor to change the markdown source and to
 114 create new markdown files. When creating new files, be sure to create new links
 115 on existing pages so visitors will be able to navigate to your
 116 new page. Run the 'ikiwiki' command to refresh the html for preview. Use 'git
 117 add' and 'git commit' to create commits to be submitted.
 118
 119 To publish your changes on the wiki, push your commits directly to the
 120 'master' branch of the openafs-wiki.git repository on gerrit.
 121
 122     git push ssh://gerrit.openafs.org/openafs-wiki.git HEAD:refs/heads/master
 123
 124 The changes will not be held by gerrit for review, rather will be merged
 125 immediately to the openafs-wiki.git repository. The html on the wiki
 126 server will be automatically updated after a successful 'git push'.
 127