]> git.vanrenterghem.biz Git - git.ikiwiki.info.git/blobdiff - doc/rcs/git.mdwn
(no commit message)
[git.ikiwiki.info.git] / doc / rcs / git.mdwn
index 000eb0b3cd6282b78c56cbec462782b74c116679..b4f639c614f199dc56f1e61d09057769df288d22 100644 (file)
@@ -5,90 +5,47 @@ 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
 
-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.
+[[!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 leaf node clone repositories is special; it has working
-directory which is used to compile the wiki, and is also used by the
+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.
+updates the published wiki itself.
 
-The other (optional) leaf node repositories are meant for you to work
+The other (optional) clones are meant for you to work
 on, and commit to, changes should then be pushed to the bare root
-repository.  In theory, you could work on the same leaf node repository
-that ikiwiki uses to compile the wiki from, and the [[cgi]] commits
-to, as long as you ensure that permissions and ownership don't hinder
-the working of the [[cgi]]. This can be done, for example, by using
-ACL's, in practice, it is easier to just setup separate clones for
-yourself.
-
-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
-  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-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. 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. 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
+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.
 
-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 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,
 "ikiwiki"), and use permissions to allow that group to commit to the bare git
@@ -121,7 +78,8 @@ 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]]
+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
@@ -129,7 +87,7 @@ 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,
+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
@@ -150,39 +108,11 @@ is the normal behaviour of ikiwiki, set the configuration of the local wiki:
       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
+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**: Currently, after
+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`. 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 <repository> <refspec>').
-    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 = <nickname>
-        branch.master.merge = <remote-ref>
-        remote.<nickname>.url = <url>
-        remote.<nickname>.fetch = <refspec>
-    
-    See git-config(1) for details.
-
-The solution is to run this command in your srcdir:
-
-    git config branch.master.remote origin
+-setup localwiki.setup -refresh`. You could use git's `post-merge` hook
+to automate that command.