GitWiki.mdwn

   1 # Using git to edit the OpenAFS wiki
   2
   3 Unlike most wiki engines, which generate html from database records,
   4 the wiki engine on the OpenAFS wiki site generates static html files
   5 from a set of source files in markdown format. Revision history of the
   6 pages is managed with git. The OpenAFS gerrit system has been
   7 configured to accept git pushes to update the wiki, which means it is
   8 now possible to update this site using git directly.
   9
  10 This page describes how to use git to create and edit pages on this wiki
  11 as an alternative to the online web form. A local wiki setup is
  12 described to allow you to preview changes before pushing them to the
  13 public wiki. One advantage to this approach is that you can edit while
  14 offline, and then submit your work later, as you would for any other git
  15 based project. Also, using git for making changes is especially handy
  16 when making a series of changes which should be committed together, such
  17 as reorganizing pages and links.
  18
  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 browser
  36
  37 ## Getting the wiki source pages
  38
  39 Use 'git clone' to get the openafs-wiki source files:
  40
  41     git clone ssh://gerrit.openafs.org/openafs-wiki.git
  42
  43 This will clone the wiki git repository to a new directory called
  44 'openafs-wiki'.
  45
  46 Set up your OpenSSH configuration to connect to the gerrit server port as
  47 described in [[GitDevelopers]].  The commit hook which generates a gerrit
  48 'change id' as described in [[GitDevelopers]] is not required for pushing
  49 openafs-wiki changes to gerrit.
  50
  51 Note: At this time, the git.openafs.org repo (gitweb) can trail the canonical
  52 repo on gerrit.openafs.org, since changes made through the web interface are
  53 not automatically propagated to the openafs gitweb. This means that if you want
  54 to make changes by pulling and pushing via git, you must pull from the
  55 gerrit.openafs.org repository above. If you pull from git.openafs.org,
  56 subsequent pushing may fail.
  57
  58 ## Setting up ikiwiki to preview your changes
  59
  60 This is an optional but recommended step. The ikiwiki software can be installed
  61 on your laptop or workstation so you can preview your changes before publishing
  62 them.  The default ikiwiki installation is intended for a server setup, so
  63 users to create pages using the web-based CGI program. In this section, a
  64 simplified setup is shown, which avoids some of the complexity of the ikiwiki
  65 setup but allows you to preview changes made to the wiki source files.
  66
  67 First, install the ikiwiki package for your system.  Use `apt` to install
  68 ikiwiki on a Debian or Ubuntu system.
  69
  70     sudo apt-get install ikiwiki
  71
  72 See [[ikiwiki downloads|http://ikiwiki.info/download]] for installation
  73 instructions for other various platforms.
  74
  75 Create a minimal ikiwiki configuration file by saving the following in
  76 the file '~/openafs-wiki.setup' (where &lt;username&gt; is your username)
  77
  78     use IkiWiki::Setup::Standard {
  79         wikiname => 'openafs-wiki',
  80         srcdir => '/home/<username>/openafs-wiki',
  81         destdir => '/home/<username>/public_html/openafs-wiki',
  82         url => 'http://localhost/openafs-wiki/',
  83         rcs => '',
  84         usedirs => 0,
  85             add_plugins => [qw{goodstuff}],
  86     }
  87
  88 The 'srcdir' should reference your local openafs-wiki git repository, created
  89 by the git clone. The 'destdir' will be created by ikiwiki when the pages are
  90 generated for preview. Note the 'rcs' setting is intentionally left empty in
  91 this setup.
  92
  93 The html files can now be generated from the openafs-wiki source by 'ikiwiki'.
  94 Run the following command to create the 'destdir' directory and create the
  95 static html files in that directory:
  96
  97     ikiwiki --setup ~/openafs-wiki.setup
  98
  99 The pages may be previewed locally by pointing your browser at:
 100
 101     file:///home/<username>/public_html/openafs-wiki/index.html
 102
 103
 104 ## Editing pages
 105
 106 You can now use your favorite text editor to change the markdown source and to
 107 create new markdown files. When creating new files, be sure to create new links
 108 on existing pages so visitors will be able to navigate to your
 109 new page. Run the following `ikiwiki` command to regenerate the html files from
 110 the source files.
 111
 112     ikiwiki --setup ~/openafs-wiki.setup --refresh
 113
 114 To preview a page, point your browser at:
 115
 116     file:///home/<username>/public_html/openafs-wiki/<NameOfPage>.html
 117
 118 When you are satified with your changes, use `git add` and `git commit` to
 119 create a commit to be submitted, then to publish your changes on the wiki, push
 120 your commits directly to the 'master' branch of the openafs-wiki.git repository
 121 on gerrit.
 122
 123     git push ssh://gerrit.openafs.org/openafs-wiki.git HEAD:refs/heads/master
 124
 125 The changes will not be held by gerrit for review.  The commit will be merged
 126 immediately to the openafs-wiki.git repository and the html on the wiki server
 127 will be automatically updated after a successful 'git push'.
 128