instructions on using git to edit 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 * [[http://ikiwiki.info|ikiwiki]] 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 <username> 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