Allow a bit more space around trails

[git.ikiwiki.info.git] / doc / rcs / git.mdwn

diff --git a/doc/rcs/git.mdwn b/doc/rcs/git.mdwn
index 0353d153558efd93c7f9403782996be7e8f028da..b4f639c614f199dc56f1e61d09057769df288d22 100644 (file)
--- a/doc/rcs/git.mdwn
+++ b/doc/rcs/git.mdwn
@@ -1,33 +1,42 @@
-[[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.
 
 [git]: http://git.or.cz/
 
 
 [Git][git] is a distributed revison control system originally developed for
 the Linux kernel. Ikiwiki supports storing a wiki in git.
 
 [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.
+Ikiwiki can run as a git `post-update` hook to update a wiki
+whenever commits come in. When running as a [[cgi]],
+ikiwiki automatically commits edited pages, and uses the
+git history to generate the [[RecentChanges]] page.
+
+Normally you can just follow the instructions in [[setup]] to create
+the git repositories and get started. To understand the details, read on.

 
 ## git repository setup
 
 
 ## git repository setup
 

-When using Git, you probably want to set up two repositories, of which
-one should be bare (meaning that it does not have a working tree
-checked out), and the other one with a working tree will be used as
-ikiwiki's srcdir for compiling the wiki. [[ikiwiki-makerepo]] can automate
-setting this up. Using a pair of repositories isn't the most obvious set up,
-but it works the best for typical ikiwiki use.
-[[tips/Laptop_wiki_with_git]] describes a different way to set up ikiwiki
-and git.
+[[!img wiki_edit_flow.svg size=490x align=right]]
+
+The suggested setup for git has a bare repository, and various
+working clones (with working directories). The bare
+repository is pushed to and pulled from the various working clones.
+
+One of the clones is special; it is the srcdir
+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.

 
 

-It is **paramount** that you **never** push to the non-bare repository
-([this FAQ entry explains why](http://git.or.cz/gitwiki/GitFaq#head-b6a3d85f677763313159eb39f7dbf4579d4ee28b)).
-Instead, if you want to work on the wiki from a remote machine, clone
-the bare repository, using either the `git` transport (if available), or
-`ssh`.
+The other (optional) clones are meant for you to work
+on, and commit to, changes should then be pushed to the bare root
+repository.

 
 

-The ikiwiki `post-commit` hook should be put in the bare repository.
+Using three or more 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.

 
 ## git repository with multiple committers
 
 
 ## git repository with multiple committers
 


@@ -35,11 +44,11 @@ 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
 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 go to the bare repository, which has a `post-update` hook that uses
-ikiwiki to pull the changes to the srcdir.
+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,
 
 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
+"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
 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


@@ -47,3 +56,63 @@ 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.)
 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`
+[[ikiwiki/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 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 -gettime` and
+you should be good to go. (You only need the slow `-gettime` option
+the first time you run setup.)  Use standard git commands to handle
+pulling from and pushing to the server.  **Note**: 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`. You could use git's `post-merge` hook
+to automate that command.