-[[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.
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
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 <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