X-Git-Url: http://git.openafs.org/?p=openafs-wiki.git;a=blobdiff_plain;f=devel%2FGitWiki.mdwn;h=a897390efe07a757f456603ae9aabd9f39ababf2;hp=f3b3d519117ca54e2af35b8ec9ab47ad9935632c;hb=aebfc8ee2725b87a5c6ca3f09af746e4f0bedbc7;hpb=7efbae817d60303a0279dd6537f9b5b96db030bb diff --git a/devel/GitWiki.mdwn b/devel/GitWiki.mdwn index f3b3d51..a897390 100644 --- a/devel/GitWiki.mdwn +++ b/devel/GitWiki.mdwn @@ -1,51 +1,47 @@ # 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. +## Prerequisites Read [[GitDevelopers]] before following the instructions on this page. -## Prerequisites - The following are needed to be able to edit the wiki pages with git. -* git installed and configured with your name and email. +* `git` is installed and configured with your name and email. * an OpenAFS gerrit account; see [[registering with gerrit|GitDevelopers]] for details. -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: +A installation of the `ikiwiki` software on your laptop or workstation is +recommended but is optional. This will allow you preview your changes before +submitting them to the OpenAFS wiki. The `ikiwiki` requires: * [[ikiwiki|http://ikiwiki.info]] installation * a basic ikiwiki setup file (shown below) -* a browser +* a basic httpd setup ## Getting the wiki source pages -Use `git clone` to get the openafs-wiki source files: +Use `git clone` to get the openafs-wiki source files from the +`gerrit.openafs.org` repo. 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 +'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 @@ -55,6 +51,19 @@ 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. +## Editing pages + +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 `master`. Do **not** +push to the gerrit review branch `refs/for/master`. + + git push origin master + +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. + ## Setting up ikiwiki to preview your changes This is an optional but recommended step. The ikiwiki software can be installed @@ -68,7 +77,7 @@ 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. +instructions for other platforms. Create a minimal ikiwiki configuration file by saving the following in the file '~/openafs-wiki.setup', where `` is your username: @@ -96,31 +105,14 @@ static html files in that directory: ikiwiki --setup ~/openafs-wiki.setup -The pages may be previewed locally by pointing your browser at: +Install a httpd server, such as apache. Configure the document root to be the +same as the `destdir` path in the `openafs-wiki.setup` file. - file:///home//public_html/openafs-wiki/index.html +The pages may be previewed locally by pointing your browser at: -## Editing pages + http://localhost/ -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. +Run the following `ikiwiki` command to regenerate the html files from the +source files after making any changes to the source files. ikiwiki --setup ~/openafs-wiki.setup --refresh - -To preview a page, point your browser at: - - file:///home//public_html/openafs-wiki/ - -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. - - git push ssh://gerrit.openafs.org/openafs-wiki.git HEAD:refs/heads/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'.