185 lines
9.0 KiB
Markdown
185 lines
9.0 KiB
Markdown
[[!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/
|
|
|
|
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.
|
|
|
|
## 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, 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
|
|
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 <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
|