web commit by http://edward.myopenid.com/: fix broken link to http://git.or.cz/gitwik...

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

diff --git a/doc/rcs/git.mdwn b/doc/rcs/git.mdwn
index d77fffeb8a26d15c9b9e98dfe50b8f03e1e7db74..f97131742518770d30bdaa63bba1af9554d02d36 100644 (file)
--- a/doc/rcs/git.mdwn
+++ b/doc/rcs/git.mdwn
@@ -1,17 +1,49 @@
 [[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][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
+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.
+commits edited pages, and uses the Git history to generate the
+[[RecentChanges]] page.
 
-Links:
+## git repository setup
 
-* [[Editing_wiki_pages_manually_with_git|GitManual]]
-* [HOWTO: ikiwiki + git][howto]
-* Common [[Git_pitfalls|/setup/git_pitfalls]] when using Git with Ikiwiki
+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.
 
-[howto]: http://fob.po8.org/node/346
+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, 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 ikiwiki `post-commit` 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 go 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.)