remove empty orphaned pages
[openafs-wiki.git] / 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 <username> 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