X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/a093824c38f6e245d9e75115c36316f0a82140b8..5e4767a594f238327a4c74f1aecc69779a237eab:/doc/rcs/git.mdwn diff --git a/doc/rcs/git.mdwn b/doc/rcs/git.mdwn index bff322d5a..9b6f2c36a 100644 --- a/doc/rcs/git.mdwn +++ b/doc/rcs/git.mdwn @@ -1,4 +1,4 @@ -[[meta title="Git"]] +[[!meta title="Git"]] [Git][git] is a distributed revison control system originally developed for the Linux kernel. Ikiwiki supports storing a wiki in git. @@ -47,24 +47,26 @@ repositories: repositories will push to/pull from. It is a bare repository, since there are problems pushing to a repository that has a working directory. This is called _repository_ in [[ikiwiki-makerepo]]'s - manual page. Nominally, this bare repository has a `post-commit` - hook that would change directory to the ikiwiki leaf node repository - below (the working directory for ikiwiki), do a _git pull_, and - refresh ikiwiki to regenerate the wiki with any new content. + manual page. Nominally, this bare repository has a `post-commit` hook + that either is or calls ikiwiki's git wrapper, which changes to the + working directory for ikiwiki, does a _git pull_, and refreshes ikiwiki + to regenerate the wiki with any new content. The [[setup]] page describes + how to do this. + * The second repository is a clone of the bare root repository, and has a working tree which is used as ikiwiki's srcdir for compiling the wiki. **Never** push to this repository. When running as a [[cgi]], the changes are committed to this repository, and pushed to the master repository above. This is called _srcdir_ in [[ikiwiki-makerepo]]'s manual page. + * The other (third, fourth, fifth, sixth -- however many pleases you) repositories are also clones of the bare root repository above -- and these have a working directory for you to work on. Use either the `git` transport (if available), or `ssh`. These repositories may be on remote machines, your laptop, whereever you find convenient to hack on your wiki. you can commit local changes to the version on - the laptop, perhaps while offline. You can browse and edit the wiki - using a local web server. Any new content should be pushed to the + the laptop, perhaps while offline. Any new content should be pushed to the bare master repository when you are ready to publish it, and then the post-commit hook of the bare repository will ensure that the ikiwiki's source directory is updated, and the ikiwiki refreshed @@ -102,45 +104,62 @@ repository, should only be writable by the wiki's admin, and *not* by the group. Take care that ikiwiki uses a umask that does not cause files in the srcdir to become group writable. (umask 022 will work.) -## Configuration - -### Ikiwiki working directory - -* Configure a cgi wrapper as usual, but configure the git wrapper to - be written to the post-commit hook of the git clone being used by - the ikiwiki (clone 0 in the image). Set in the configuration: - - gitorigin_branch=> "origin", - ## git post-commit wrapper - wrapper => "/path/to/bare/repo/.git/hooks/post-commit", - - - -### Working clones (Clone 1 .. N in the image) - -* By default, ikiwiki pulls and pushes from `origin`. This is not - ideal for the working clones, since the user might go through - several iterations of a posting before pushing to the bare root of - the repository tree. In the configuration, set: - - gitorigin_branch => "", - ## git post-commit wrapper - wrapper => "/working/dir/.git/hooks/post-commit", - - Then just committing should refresh the ikiwiki on the local host. - -* You can optionally enable to the [[plugins/mirrorlist]] plugin, - and configure it so that each page links to the corresponding page on the - server. - -Now just run `ikiwiki -setup wiki.setup -getctime` and you should be -good to go. (You only need the slow `-getctime` option the first time you -run setup.) - -Use standard git commands to handle pulling from and pushing to the server. - -Note: Currently, after pulling changes, you will need to manually update -the wiki, with a command such as `ikiwiki -setup wiki.setup -refresh`. This -is because git 1.5.4 doesn't have a hook that is run locally after pulling -changes. Newer versions of git will have a `post-merge` hook that should -work for this purpose. +## Optionally using a local wiki to preview changes + +When working on the "working clones" to add content to your wiki, +it is common (but optional) practice to preview your changes using a +private wiki on the local host before publishing the updates by +sending it to the root repository. If you do want to setup a private +wiki, you will have to have another setup file and and an ikiwiki +installation on your local machine. You will need all the packages +this implies -- a web server, git, ikiwiki, etc. However, there is a +_caveat_: by default, ikiwiki pulls and pushes from `origin`. This is +not ideal for the working clones on the local machine, since you might +go through several iterations of a page before pushing to the bare +root of the repository tree (and thus publishing it on your public wiki). +You do not want the action of refreshing the local wiki in order to +review your work to accidentally publish the +contents before you are ready. In order to prevent the git push that +is the normal behaviour of ikiwiki, set the configuration of the local wiki: + + gitorigin_branch => "", + ## git post-commit wrapper + wrapper => "/working/dir/.git/hooks/post-commit", + +Then just committing should refresh the private ikiwiki on the local +host. Now just run `ikiwiki -setup localwiki.setup -getctime` and +you should be good to go. (You only need the slow `-getctime` option +the first time you run setup.) Use standard git commands to handle +pulling from and pushing to the server. **Note**: Currently, after +pulling changes from the bare root repository, you will need to +manually update the local wiki, with a command such as `ikiwiki +-setup localwiki.setup -refresh`. This is because git 1.5.4 doesn't +have a hook that is run locally after pulling changes. Newer +versions of git will have a `post-merge` hook that should work for +this purpose. + +## Fix for error on git pull origin + +Error message when running git pull origin: + + You asked me to pull without telling me which branch you + want to merge with, and 'branch.master.merge' in + your configuration file does not tell me either. Please + name which branch you want to merge on the command line and + try again (e.g. 'git pull '). + See git-pull(1) for details on the refspec. + + If you often merge with the same branch, you may want to + configure the following variables in your configuration + file: + + branch.master.remote = + branch.master.merge = + remote..url = + remote..fetch = + + See git-config(1) for details. + +The solution is to run this command in your srcdir: + + git config branch.master.remote origin