# Using git to edit the OpenAFS wiki
-Unlike most wiki engines, which generate html from database records,
-the wiki engine on the OpenAFS wiki site generates static html files
-from a set of source files in markdown format. Revision history of the
-pages is managed with git. The OpenAFS gerrit system has been
-configured to accept git pushes to update the wiki, which means it is
-now possible to update this site using git directly.
-
-This page describes how to use git to create and edit pages on this wiki
-as an alternative to the online web form. A local wiki setup is
-described to allow you to preview changes before pushing them to the
-public wiki. One advantage to this approach is that you can edit while
-offline, and then submit your work later, as you would for any other git
-based project. Also, using git for making changes is especially handy
-when making a series of changes which should be committed together, such
-as reorganizing pages and links.
-
+Unlike most wiki engines, which generate html from database records, the wiki
+engine on the OpenAFS wiki site generates static html files from a set of
+source files in markdown format. Revision history of the pages is managed with
+git. The OpenAFS gerrit system has been configured to accept git pushes to
+update the wiki, which means it is now possible to update this site using git
+directly.
+
+This page describes how to use git to create and edit pages on this wiki as an
+alternative to the online web form. A local wiki setup is described to allow
+you to preview changes before pushing them to the public wiki. One advantage to
+this approach is that you can edit while offline and then submit your work
+later, as you would for any other git based project. Using git for making
+changes is especially handy when making a series of changes which should be
+committed together, such as reorganizing pages and links.
+
+## Setup
Read [[GitDevelopers]] before following the instructions on this page.
-## Prerequisites
-
-The following are needed to be able to edit the wiki pages with git.
+Create an OpenAFS gerrit account if you do not already have one. See
+[[registering with gerrit|GitDevelopers]] for details.
-* git installed and configured with your name and email.
-* an OpenAFS gerrit account; see [[registering with gerrit|GitDevelopers]] for details.
+[Install git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git)
+on your system.
-A installation of the ikiwiki software on your laptop or workstation is
-recommended so you can preview your changes before submitting them to the
-OpenAFS wiki. This requires:
+Set up your OpenSSH configuration to connect to the gerrit server as
+described in [[GitDevelopers]]. Do not set up the commit hook to generate
+gerrit change numbers in commit messages. Gerrit change ids are not
+used in the wiki pages.
-* [[ikiwiki|http://ikiwiki.info]] installation
-* a basic ikiwiki setup file (shown below)
-* a browser
+ Host gerrit.openafs.org
+ User <username>
+ IdentityFile ~/.ssh/<ident>
+ Port 29418
+ HostKeyAlgorithms +ssh-rsa
+ PubkeyAcceptedAlgorithms +ssh-rsa
-## Getting the wiki source pages
+## Getting the wiki source
Use `git clone` to get the openafs-wiki source files:
- git clone ssh://gerrit.openafs.org/openafs-wiki.git
-
-This will clone the wiki git repository to a new directory called
-'openafs-wiki'.
-
-Set up your OpenSSH configuration to connect to the gerrit server port as
-described in [[GitDevelopers]]. The commit hook which generates a gerrit
-'change id' as described in [[GitDevelopers]] is not required for pushing
-openafs-wiki changes to gerrit.
-
-Note: At this time, the git.openafs.org repo (gitweb) can trail the canonical
-repo on gerrit.openafs.org, since changes made through the web interface are
-not automatically propagated to the openafs gitweb. This means that if you want
-to make changes by pulling and pushing via git, you must pull from the
-gerrit.openafs.org repository above. If you pull from git.openafs.org,
-subsequent pushing may fail.
-
-## Setting up ikiwiki to preview your changes
-
-This is an optional but recommended step. The ikiwiki software can be installed
-on your local machine so you can preview your changes before publishing them on
-the wiki. The default ikiwiki installation instructions are intended for a
-server setup. A simplified, minimal setup is shown here.
-
-First, install the ikiwiki package for your system. Use `apt` to install
-ikiwiki on a Debian or Ubuntu system.
-
- sudo apt-get install ikiwiki
-
-See [[ikiwiki downloads|http://ikiwiki.info/download]] for installation
-instructions for other various platforms.
+ $ git clone ssh://gerrit.openafs.org/openafs-wiki.git
-Create a minimal ikiwiki configuration file by saving the following in
-the file '~/openafs-wiki.setup', where `<username>` is your username:
+WARNING: **Do not** use the mirror on `git.openafs.org` or your pushes will fail.
- use IkiWiki::Setup::Standard {
- wikiname => 'openafs-wiki',
- srcdir => '/home/<username>/openafs-wiki',
- destdir => '/home/<username>/public_html/openafs-wiki',
- url => 'http://localhost/openafs-wiki/',
- rcs => '',
- usedirs => 1,
- add_plugins => [qw{goodstuff}],
- }
+## Local preview (optional)
-The 'srcdir' should reference your local openafs-wiki git repository, created
-by the git clone. The 'destdir' will be created by ikiwiki when the pages are
-generated for preview. The 'destdir' may be set to a DocumentRoot directory if
-you have a local http server to show the pages.
+This step is optional, but recommended. It is possible to install the `ikiwiki`
+software locally to allow you to preview your changes before pushing them.
-Note the 'rcs' setting is intentionally left empty in this setup.
+*Debian/Ubuntu*
-The html files can now be generated from the openafs-wiki source by 'ikiwiki'.
-Run the following command to create the 'destdir' directory and create the
-static html files in that directory:
+ $ sudo apt install make ikiwiki python3 xdg-utils
- ikiwiki --setup ~/openafs-wiki.setup
+*Fedora*
-The pages may be previewed locally by pointing your browser at:
+ $ sudo yum install make ikiwiki python3 xdg-utils
- file:///home/<username>/public_html/openafs-wiki/index.html
+For other platforms, you may need to install `ikiwiki` from source. See
+[https://ikiwiki.info/install](https://ikiwiki.info/install/) for instructions.
-## Editing pages
+A makefile is provided for a previewing your local changes in your browser to
+let you check your changes before doing a `git push`. Run `make preview` in
+the top-level directory to generate the html and preview the wiki in a browser:
-You can now use your favorite text editor to change the markdown source and to
-create new markdown files. When creating new files, be sure to create new links
-on existing pages so visitors will be able to navigate to your
-new page. Run the following `ikiwiki` command to regenerate the html files from
-the source files.
+ $ make preview
+ (Press <control>-c to exit.)
- ikiwiki --setup ~/openafs-wiki.setup --refresh
+Run `make clean` to cleanup the files created after a preview.
-To preview a page, point your browser at:
+ $ make clean
- file:///home/<username>/public_html/openafs-wiki/
+## Pushing changes
-When you are satified with your changes, use `git add` and `git commit` to
-create a commit to be submitted, then to publish your changes on the wiki, push
-your commits directly to the 'master' branch of the openafs-wiki.git repository
-on gerrit.
+When you are satisfied with your changes, use `git add` and `git commit` to
+create a commit to be submitted. To publish your changes on the wiki, push your
+commits *directly* to the **master** branch of
+`gerrit.openafs.org/openafs-wiki.git`. **Do not** push to the gerrit review
+branch `refs/for/master`.
- git push ssh://gerrit.openafs.org/openafs-wiki.git HEAD:refs/heads/master
+ $ git push origin master
-The changes will not be held by gerrit for review. The commit will be merged
-immediately to the openafs-wiki.git repository and the html on the wiki server
-will be automatically updated after a successful 'git push'.
+The commit will be merged immediately to the openafs-wiki.git repository. The
+html on the wiki server will be automatically updated after a successful `git
+push` after a few moments. The changes will not be held by gerrit for review.
git://git.openafs.org / openafs-wiki.git / blobdiff