Merge branch 'master' of git://git.ikiwiki.info

6 files changed, 193 insertions, 15 deletions

diff --git a/doc/rcs/cvs.mdwn b/doc/rcs/cvs.mdwn
new file mode 100644
index 000000000..9beb08ece
--- /dev/null
+++ b/doc/rcs/cvs.mdwn
@@ -0,0 +1,28 @@
+If you really need to, you can use [[!wikipedia desc="CVS" Concurrent Versions System]]
+with ikiwiki.
+
+### Usage
+7. Install [[!cpan File::chdir]], [[!cpan File::ReadBackwards]],
+[cvsps](http://www.cobite.com/cvsps/), and
+[cvsweb](http://www.freebsd.org/projects/cvsweb.html) or the like.
+7. Adjust CVS-related parameters in your setup file.
+
+Consider creating `$HOME/.cvsrc` if you don't have one already; the plugin doesn't need it, but you yourself might. Here's a good general-purpose one:
+
+    cvs -q
+    checkout -P
+    update -dP
+    diff -u
+    rdiff -u
+
+### Implementation details
+* [[ikiwiki-makerepo]]:
+ * creates a repository,
+ * imports `$SRCDIR` into top-level module `ikiwiki` (vendor tag IKIWIKI, release tag PRE_CVS),
+ * configures the post-commit hook in `CVSROOT/loginfo`.
+
+### To do
+* Have `ikiwiki-makerepo` set up NetBSD-like `log_accum` and `commit_prep` scripts that coalesce commits into changesets. Reasons:
+    7. Obviates the need to scrape the repo's complete history to determine the last N changesets. (Repositories without such records can fall back on the `cvsps` and `File::ReadBackwards` code.)
+    7. Arranges for ikiwiki to be run once per changeset, rather than CVS's once per committed file (!), which is a waste at best and bug-inducing at worst. (Currently, on multi-directory commits, only the first directory's changes get mentioned in [[recentchanges|plugins/recentchanges]].)
+* Perhaps prevent web edits from attempting to create `.../CVS/foo.mdwn` (and `.../cvs/foo.mdwn` on case-insensitive filesystems); thanks to the CVS metadata directory, the attempt will fail anyway (and much more confusingly) if we don't.
diff --git a/doc/rcs/cvs/discussion.mdwn b/doc/rcs/cvs/discussion.mdwn
new file mode 100644
index 000000000..645b2388b
--- /dev/null
+++ b/doc/rcs/cvs/discussion.mdwn
@@ -0,0 +1,149 @@
+I've started reviewing this, and the main thing I don't like is the
+post-commit wrapper wrapper that ikiwiki-makerepo is patched to set up.
+That just seems unnecessarily complicated. Why can't ikiwiki itself detect
+the "cvs add <directory>" call and avoid doing anything in that case?
+--[[Joey]] 
+
+> The wrapper wrapper does three things:
+>
+> 7. It ignores `cvs add <directory>`, since this is a weird CVS
+> behavior that ikiwiki gets confused by and doesn't need to act on.
+> 7. It prevents `cvs` locking against itself: `cvs commit` takes a
+> write lock and runs the post-commit hook, which runs `cvs update`,
+> which wants a read lock and sleeps forever -- unless the post-commit
+> hook runs in the background so the commit can "finish".
+> 7. It fails silently if the ikiwiki post-commit hook is missing.
+> CVS doesn't have any magic post-commit filenames, so hooks have to
+> be configured explicitly. I don't think a commit will actually fail
+> if a configured post-commit hook is missing (though I can't test
+> this at the moment).
+>
+> Thing 1 can probably be handled within ikiwiki, if that seems less
+> gross to you.
+
+>> It seems like it might be. You can use a `getopt` hook to check
+>> `@ARGV` to see how it was called. --[[Joey]] 
+
+>>> This does the trick iff the post-commit wrapper passes its args
+>>> along. Committed on my branch. This seems potentially dangerous,
+>>> since the args passed to ikiwiki are influenced by web commits.
+>>> I don't see an exploit, but for paranoia's sake, maybe the wrapper
+>>> should only be built with execv() if the cvs plugin is loaded?
+>>> --[[schmonz]]
+
+>>>> Hadn't considered that. While in wrapper mode the normal getopt is not
+>>>> done, plugin getopt still runs, and so any unsafe options that 
+>>>> other plugins support could be a problem if another user runs
+>>>> the setuid wrapper and passes those options through. --[[Joey]]
+
+>>>>> I've tried compiling the argument check into the wrapper as
+>>>>> the first thing main() does, and was surprised to find that
+>>>>> this doesn't prevent the `cvs add <dir>` deadlock in a web
+>>>>> commit. I was convinced this'd be a reasonable solution,
+>>>>> especially if conditionalized on the cvs plugin being loaded,
+>>>>> but it doesn't work. And I stuck debug printfs at the beginning
+>>>>> of all the rcs_foo() subs, and whatever `cvs add <dir>` is
+>>>>> doing to ikiwiki isn't visible to my plugin, because none of
+>>>>> those subs are getting called. Nuts. Can you think of anything
+>>>>> else that might solve the problem, or should I go back to
+>>>>> generating a minimal wrapper wrapper that checks for just
+>>>>> this one thing? --[[schmonz]]
+
+>>>>>> I don't see how there could possibly be a difference between
+>>>>>> ikiwiki's C wrapper and your shell wrapper wrapper here. --[[Joey]]
+
+>>>>>>> I was comparing strings overly precisely. Fixed on my branch.
+>>>>>>> I've also knocked off the two most pressing to-do items. I
+>>>>>>> think the plugin's ready for prime time. --[[schmonz]]
+
+> Thing 2 I'm less sure of. (I'd like to see the web UI return
+> immediately on save anyway, to a temporary "rebuilding, please wait
+> if you feel like knowing when it's done" page, but this problem
+> with CVS happens with any kind of commit, and could conceivably
+> happen with some other VCS.)
+
+>> None of the other VCSes let a write lock block a read lock, apparently.
+>> 
+>> Anyway, re the backgrounding, when committing via the web, the
+>> post-commit hook doesn't run anyway; the rendering is done via the
+>> ikiwiki CGI. It would certianly be nice if it popped up a quick "working"
+>> page and replaced it with the updated page when done, but that's
+>> unrelated;  the post-commit
+>> hook only does rendering when committing using the VCS directly. The
+>> backgrounding you do actually seems safe enough -- but tacking
+>> on a " &" to the ikiwiki wrapper call doesn't need a wrapper script,
+>> does it? --[[Joey]]
+
+>>> Nope, it works fine to append it to the `CVSROOT/loginfo` line.
+>>> Fixed on my branch. --[[schmonz]]
+
+> Thing 3 I think I did in order to squelch the error messages that
+> were bollixing up the CGI. It was easy to do this in the wrapper
+> wrapper, but if that's going away, it can be done just as easily
+> with output redirection in `CVSROOT/loginfo`.
+>
+> --[[schmonz]]
+
+>> If the error messages screw up the CGI they must go to stdout.
+>> I thought we had stderr even in the the CVS dark ages. ;-) --[[Joey]] 
+
+>>> Some messages go to stderr, but definitely not all. That's why
+>>> I wound up reaching for IPC::Cmd, to execute the command line
+>>> safely while shutting CVS up. Anyway, I've tested what happens
+>>> if a configured post-commit hook is missing, and it seems fine,
+>>> probably also thanks to IPC::Cmd.
+>>> --[[schmonz]]
+
+----
+
+
+Further review.. --[[Joey]] 
+
+I don't understand what `cvs_shquote_commit` is
+trying to do with the test message, but it seems
+highly likely to be insecure; I never trust anything 
+that relies on safely quoting user input passed to the shell. 
+
+(As an aside, `shell_quote` can die on certian inputs.)
+
+Seems to me that, if `IPC::Cmd` exposes input to the shell
+(which I have not verified but its docs don't specify; a bad sign)
+you chose the wrong tool and ended up doing down the wrong
+route, dragging in shell quoting problems and fixes. Since you
+chose to use `IPC::Cmd`	just because you wanted to shut
+up CVS stderr, my suggestion would be to use plain `system`
+to run the command, with stderr temporarily sent to /dev/null:
+
+	open(my $savederr, ">&STDERR");
+	open(STDERR, ">", "/dev/null");
+	my $ret=system("cvs", "-Q", @_);
+	open(STDERR, ">$savederr");
+
+`cvs_runcvs` should not take an array reference. It's
+usual for this type of function to take a list of parameters
+to pass to the command.
+
+> Thanks for reading carefully. I've tested your suggestions and
+> applied them on my branch. --[[schmonz]]
+
+----
+
+I've abstracted out CVS's involvement in the wrapper, adding a new
+"wrapperargcheck" hook to examine `argc/argv` and return success or
+failure (failure causes the wrapper to terminate) and implementing
+this hook in the plugin. In the non-CVS case, the check immediately
+returns success, so the added overhead is just a function call.
+
+Given how rarely anything should need to reach in and modify the
+wrapper -- I'd go so far as to say we shouldn't make it too easy
+-- I don't think it's worth the effort to try and design a more
+general-purpose way to do so. If and when some other problem thinks
+it wants to be solved by a new wrapper hook, it's easy enough to add
+one. Until then, I'd say it's more important to keep the wrapper as
+short and clear as possible. --[[schmonz]]
+
+> I've committed a slightly different hook, which should be general enough
+> that `IkiWiki::Receive` can also use it, so please adapt your code to
+> that. --[[Joey]]
+
+>> Done. --[[schmonz]].
diff --git a/doc/rcs/details.mdwn b/doc/rcs/details.mdwn
index 6492cf38c..013ddb745 100644
--- a/doc/rcs/details.mdwn
+++ b/doc/rcs/details.mdwn
@@ -288,3 +288,5 @@ user for cleanup.  This is less neat than it could be, in that a conflict marked
 revision gets committed to the repository.
 
 ## [[bzr]]
+
+## [[cvs]]
diff --git a/doc/rcs/git.mdwn b/doc/rcs/git.mdwn
index 000eb0b3c..c627792d7 100644
--- a/doc/rcs/git.mdwn
+++ b/doc/rcs/git.mdwn
@@ -28,12 +28,7 @@ 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.  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.
+repository.
 
 So, to reiterate, when using Git, you probably want to set up three
 repositories:
@@ -41,9 +36,9 @@ 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
+  git does not support 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
+  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
@@ -51,10 +46,11 @@ repositories:
 
 * 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 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 --
@@ -87,8 +83,8 @@ 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
diff --git a/doc/rcs/svn.mdwn b/doc/rcs/svn.mdwn
index f8c44b6eb..7aa682978 100644
--- a/doc/rcs/svn.mdwn
+++ b/doc/rcs/svn.mdwn
@@ -1,4 +1,4 @@
-[Subversion](http://subversion.tigris.org/) is a revision control system. While ikiwiki is relatively
+[Subversion](http://subversion.tigris.org/) is a [[revision control system|rcs]]. While ikiwiki is relatively
 independent of the underlying revision control system, and can easily be
 used without one, using it with Subversion or another revision control
 system is recommended.
diff --git a/doc/rcs/tla.mdwn b/doc/rcs/tla.mdwn
index cad5d51f4..79eecd627 100644
--- a/doc/rcs/tla.mdwn
+++ b/doc/rcs/tla.mdwn
@@ -2,6 +2,9 @@
 [GNU](http://www.gnu.org/) [Arch](http://www.gnuarch.org/) revision control
 system. Ikiwiki supports storing a wiki in tla.
 
+Warning: Since tla is not being maintained, neither is this plugin, and
+using ikiwiki with tla is not recommended.
+
 Ikiwiki can run as a [[post-commit]] hook to update a wiki whenever commits
 come in. When running as a [[cgi]] with tla, ikiwiki automatically
 commits edited pages to the Arch repostory, and uses the Arch