X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/74baaeba00c90cd7a027e40e2f6d65695341a0e1..fcc1ab53ff97594ced1e4d2d462c0e16c58d7b3e:/doc/rcs/git.mdwn?ds=sidebyside diff --git a/doc/rcs/git.mdwn b/doc/rcs/git.mdwn index eeb05d5f2..1b66493dd 100644 --- a/doc/rcs/git.mdwn +++ b/doc/rcs/git.mdwn @@ -1,7 +1,184 @@ -[[meta title="Git"]] +[[!meta title="Git"]] -[Git](http://git.or.cz) is a distributed revison control system originally developed for the Linux kernel. Ikiwiki supports storing a wiki in git. +[Git][git] is a distributed revison control system originally developed for +the Linux kernel. Ikiwiki supports storing a wiki in git. -Ikiwiki can run as a post-update hook to update a wiki whenever commits +[git]: http://git.or.cz/ + +Ikiwiki can run as a `post-update` hook to update a wiki whenever commits come in. When running as a [[cgi]] with Git, ikiwiki automatically -commits edited pages, and uses the Git history to generate the [[RecentChanges]] page. \ No newline at end of file +commits edited pages, and uses the Git history to generate the +[[RecentChanges]] page. + +## git repository setup + +The suggested setup for git is a set of repositories setup like a +shallow, single level tree, with a bare repository (meaning that it +does not have a working tree checked out) at the root, and various +working clones (with working directories) as leaf nodes. The root +(bare) repository is meant to be pushed to and pulled from the various +working clones. + +One of the leaf node clone repositories is special; it has working +directory which is used to compile the wiki, and is also used by the +[[cgi]] to commit changes made via the web interface. It is special +since the `post-update` hook for the bare root repository is used to +trigger an update of this repository, and then an ikiwiki refresh +updates the published wiki itself. + +The other (optional) leaf node repositories are meant for you to work +on, and commit to, changes should then be pushed to the bare root +repository. + +So, to reiterate, when using Git, you probably want to set up three +repositories: + +* The root repository. This should be a bare repository (meaning that + it does not have a working tree checked out), which the other + repositories will push to/pull from. It is a bare repository, since + git does not support pushing to a repository that has a working + directory. This is called _repository_ in [[ikiwiki-makerepo]]'s + manual page. This bare repository has a `post-update` 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. It is wise to not make + changes or commits directly to this repository, to avoid conflicting + with ikiwiki's own changes. 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, wherever you find convenient to + hack on your wiki. You can commit local changes to the version on + 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-update hook of the bare repository will ensure that the + ikiwiki's source directory is updated, and the ikiwiki refreshed + with the new content. + +Using three or more of repositories isn't the most obvious set up, but +it works the best for typical ikiwiki use. [[ikiwiki-makerepo]] can +automate setting this up for the common case where there is no +pre-existing wiki. [[tips/Laptop_wiki_with_git]] describes a different +way to set up ikiwiki and git. + +It is **paramount** that you **never** push to the non-bare repository +([this FAQ entry explains why](http://git.or.cz/gitwiki/GitFaq#head-b96f48bc9c925074be9f95c0fce69bcece5f6e73)). +Instead, clone the bare repository as mentioned above, and push +**only** to the bare repository. + +The ikiwiki `post-update` hook should be put in the bare repository. + +## git repository with multiple committers + +It can be tricky to get the permissions right to allow multiple people to +commit to an ikiwiki git repository. As the [[security]] page mentions, +for a secure ikiwiki installation, only one person should be able to write +to ikiwiki's srcdir. When other committers make commits, their commits +should be pushed to the bare repository, which has a `post-update` hook +that uses ikiwiki to pull the changes to the srcdir. + +One setup that will work is to put all committers in a group (say, +"ikiwiki"), and use permissions to allow that group to commit to the bare git +repository. Make both the post-update hook and ikiwiki.cgi be setgid +to the group, as well as suid to the user who admins the wiki. The +`wrappergroup` [[setup_file_option|usage]] can be used to make the wrappers +be setgid to the right group. Then the srcdir, including its git +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.) + +## git repository with untrusted committers + +By default, anyone who can commit to the git repository can modify any file +on the wiki however they like. A `pre-receive` hook can be set up to limit +incoming commits from untrusted users. Then the same limits that are placed +on edits via the web will be in effect for commits to git for the users. +They will not be allowed to edit locked pages, they will only be able to +delete pages that the [[plugins/remove]] configuration allows them to +remove, and they will only be allowed to add non-page attachments that the +[[plugins/attachment]] configuration allows. + +To enable this, you need to set up the git repository to have multiple +committers. Trusted committers, including the user that ikiwiki runs as, +will not have their commits checked by the `pre-receive` hook. Untrusted +committers will have their commits checked. The configuration settings to +enable are `git_test_receive_wrapper`, which enables generation of a +`pre-receive` hook, and `untrusted_committers`, which is a list of +usernames of the untrusted committers. + +Note that when the `pre-receive` hook is checking incoming changes, it +ignores the git authorship information, and uses the username of the unix +user who made the commit. Then tests including the `locked_pages` [[PageSpec]] +are checked to see if that user can edit the pages in the commit. + +You can even set up an [[anonymous_user|tips/untrusted_git_push]], to allow +anyone to push changes in via git rather than using the web interface. + +## 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 + git_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