From: joey Date: Tue, 21 Aug 2007 04:25:03 +0000 (+0000) Subject: reorg all the pages about rcs backends. Fix all links X-Git-Tag: 2.6~68 X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/commitdiff_plain/74baaeba00c90cd7a027e40e2f6d65695341a0e1 reorg all the pages about rcs backends. Fix all links --- diff --git a/doc/TourBusStop.mdwn b/doc/TourBusStop.mdwn index 77e9c7058..05ed6c21a 100644 --- a/doc/TourBusStop.mdwn +++ b/doc/TourBusStop.mdwn @@ -4,7 +4,7 @@ This wiki serves as the home for the ikiwiki wiki engine, providing collaborativ [[ikiwiki|/index]] provides a wiki engine with several [[/features]] unique or uncommon amongst wiki engines: -* Rather than inventing yet another simplistic, linear version control system, ikiwiki uses a standard version control system such as [[Subversion]] or [[Git]]. You can edit a wiki by committing to your repository, as well as through a traditional web interface. This makes ikiwiki ideal for collaborative software development; just keep your wiki in version control next to your software. You can also take full advantage of the features of these systems; for instance, you can keep a local branch of your wiki via [[Git]]. +* Rather than inventing yet another simplistic, linear version control system, ikiwiki uses a standard version control system such as [[rcs/Subversion]] or [[rcs/Git]]. You can edit a wiki by committing to your repository, as well as through a traditional web interface. This makes ikiwiki ideal for collaborative software development; just keep your wiki in version control next to your software. You can also take full advantage of the features of these systems; for instance, you can keep a local branch of your wiki via [[rcs/Git]]. * You can turn any set of pages into a [[blog]] or similar news feed, complete with RSS and Atom support. You can run your weblog on ikiwiki (and [[many people do|ikiwikiusers]]), run a Planet-like [[aggregator|plugins/aggregate]] for external feeds, or keep a [[TODO]] and [[bug|bugs]] list with tags for completed items. diff --git a/doc/about_rcs_backends.mdwn b/doc/about_rcs_backends.mdwn deleted file mode 100644 index 7af4a952e..000000000 --- a/doc/about_rcs_backends.mdwn +++ /dev/null @@ -1,223 +0,0 @@ -A few bits about the RCS backends - -[[toc ]] - -## Terminology - -``web-edit'' means that a page is edited by using the web (CGI) interface -as opposed to using a editor and the RCS interface. - - -## [[Subversion]] - -Subversion was the first RCS to be supported by ikiwiki. - -### How does it work internally? - -Master repository M. - -RCS commits from the outside are installed into M. - -There is a working copy of M (a checkout of M): W. - -HTML is generated from W. rcs_update() will update from M to W. - -CGI operates on W. rcs_commit() will commit from W to M. - -For all the gory details of how ikiwiki handles this behind the scenes, -see [[commit-internals]]. - -You browse and web-edit the wiki on W. - -W "belongs" to ikiwiki and should not be edited directly. - - -## [darcs](http://darcs.net/) (not yet included) - -Support for using darcs as a backend is being worked on by [Thomas -Schwinge](mailto:tschwinge@gnu.org), although development is on hold curretly. -There is a patch in [[todo/darcs]]. - -### How will it work internally? - -``Master'' repository R1. - -RCS commits from the outside are installed into R1. - -HTML is generated from R1. HTML is automatically generated (by using a -``post-hook'') each time a new change is installed into R1. It follows -that rcs_update() is not needed. - -There is a working copy of R1: R2. - -CGI operates on R2. rcs_commit() will push from R2 to R1. - -You browse the wiki on R1 and web-edit it on R2. This means for example -that R2 needs to be updated from R1 if you are going to web-edit a page, -as the user otherwise might be irritated otherwise... - -How do changes get from R1 to R2? Currently only internally in -rcs\_commit(). Is rcs\_prepedit() suitable? - -It follows that the HTML rendering and the CGI handling can be completely -separated parts in ikiwiki. - -What repository should [[RecentChanges]] and [[History]] work on? R1? - -#### Rationale for doing it differently than in the Subversion case - -darcs is a distributed RCS, which means that every checkout of a -repository is equal to the repository it was checked-out from. There is -no forced hierarchy. - -R1 is nevertheless called the master repository. It's used for -collecting all the changes and publishing them: on the one hand via the -rendered HTML and on the other via the standard darcs RCS interface. - -R2, the repository the CGI operates on, is just a checkout of R1 and -doesn't really differ from the other checkouts that people will branch -off from R1. - -(To be continued.) - -#### Another possible approach - -Here's what I (tuomov) think, would be a “cleaner” approach: - - 1. Upon starting to edit, Ikiwiki gets a copy of the page, and `darcs changes --context`. - This context _and_ the present version of the page are stored in as the “version” of the - page in a hidden control of the HTML. - Thus the HTML includes all that is needed to generate a patch wrt. to the state of the - repository at the time the edit was started. This is of course all that darcs needs. - 2. Once the user is done with editing, _Ikiwiki generates a patch bundle_ for darcs. - This should be easy with existing `Text::Diff` or somesuch modules, as the Web edits - only concern single files. The reason why the old version of the page is stored in - the HTML (possibly compressed) is that the diff can be generated. - 3. Now this patch bundle is applied with `darcs apply`, or sent by email for moderation… - there are many possibilities. - -This approach avoids some of the problems of concurrent edits that the previous one may have, -although there may be conflicts, which may or may not propagate to the displayed web page. -(Unfortunately there is not an option to `darcs apply` to generate some sort of ‘confliction resolution -bundle’.) Also, only one repository is needed, as it is never directly modified -by Ikiwiki. - -This approach might be applicable to other distributed VCSs as well, although they're not as oriented -towards transmitting changes with standalone patch bundles (often by email) as darcs is. - -> The mercurial plugin seems to just use one repo and edit it directly - is -> there some reason that's okay there but not for darcs? I agree with tuomov -> that having just the one repo would be preferable; the point of a dvcs is -> that there's no difference between one repo and another. I've got a -> darcs.pm based on mercurial.pm, that's almost usable... --bma - ->> IMHO it comes down to whatever works well for a given RCS. Seems like ->> the darcs approach _could_ be done with most any distributed system, but ->> it might be overkill for some (or all?) While there is the incomplete darcs ->> plugin in [[todo/darcs]], if you submit one that's complete, I will ->> probably accept it into ikiwiki.. --[[Joey]] - -## [[Git]] - -Regarding the Git support, Recai says: - -I have been testing it for the past few days and it seems satisfactory. I -haven't observed any race condition regarding the concurrent blog commits -and it handles merge conflicts gracefully as far as I can see. - -As you may notice from the patch size, GIT support is not so trivial to -implement (for me, at least). Being a fairly fresh code base it has some -bugs. It also has some drawbacks (especially wrt merge which was the hard -part). GIT doesn't have a similar functionality like 'svn merge -rOLD:NEW -FILE' (please see the relevant comment in mergepast for more details), so I -had to invent an ugly hack just for the purpose. - -By design, Git backend uses a "master-clone" repository pair approach in contrast -to the single repository approach (here, _clone_ may be considered as the working -copy of a fictious web user). Even though a single repository implementation is -possible, it somewhat increases the code complexity of backend (I couldn't figure -out a uniform method which doesn't depend on the prefered repository model, yet). -By exploiting the fact that the master repo and _web user_'s repo (`srcdir`) are all -on the same local machine, I suggest to create the latter with the "`git clone -l -s`" -command to save disk space. - -Note that, as a rule of thumb, you should always put the rcs wrapper (`post-update`) -into the master repository (`.git/hooks/`) as can be noticed in the Git wrappers of -the sample [[ikiwiki.setup]]. - -## [[Mercurial]] - -The Mercurial backend is still in a early phase, so it may not be mature -enough, but it should be simple to understand and use. - -As Mercurial is a distributed RCS, it lacks the distinction between -repository and working copy (every wc is a repo). - -This means that the Mercurial backend uses directly the repository as -working copy (the master M and the working copy W described in the svn -example are the same thing). - -You only need to specify 'srcdir' (the repository M) and 'destdir' (where -the HTML will be generated). - -Master repository M. - -RCS commit from the outside are installed into M. - -M is directly used as working copy (M is also W). - -HTML is generated from the working copy in M. rcs_update() will update -to the last committed revision in M (the same as 'hg update'). -If you use an 'update' hook you can generate automatically the HTML -in the destination directory each time 'hg update' is called. - -CGI operates on M. rcs_commit() will commit directly in M. - -If you have any question or suggestion about the Mercurial backend -please refer to [Emanuele](http://nerd.ocracy.org/em/) - -## [[tla]] - -## rcs - -There is a patch that needs a bit of work linked to from [[todo/rcs]]. - -## [Monotone](http://monotone.ca/) - -In normal use, monotone has a local database as well as a workspace/working copy. -In ikiwiki terms, the local database takes the role of the master repository, and -the srcdir is the workspace. As all monotone workspaces point to a default -database, there is no need to tell ikiwiki explicitly about the "master" database. It -will know. - -The patch currently supports normal committing and getting the history of the page. -To understand the parallel commit approach, you need to understand monotone's -approach to conflicts: - -Monotone allows multiple micro-branches in the database. There is a command, -`mtn merge`, that takes the heads of all these branches and merges them back together -(turning the tree of branches into a dag). Conflicts in monotone (at time of writing) -need to be resolved interactively during this merge process. -It is important to note that having multiple heads is not an error condition in a -monotone database. This condition will occur in normal use. In this case -'update' will choose a head if it can, or complain and tell the user to merge. - -For the ikiwiki plugin, the monotone ikiwiki plugin borrows some ideas from the svn ikiwiki plugin. -On prepedit() we record the revision that this change is based on (I'll refer to this as the prepedit revision). When the web user -saves the page, we check if that is still the current revision. If it is, then we commit. -If it isn't then we check to see if there were any changes by anyone else to the file -we're editing while we've been editing (a diff bewteen the prepedit revision and the current rev). -If there were no changes to the file we're editing then we commit as normal. - -It is only if there have been parallel changes to the file we're trying to commit that -things get hairy. In this case the current approach is to -commit the web changes as a branch from the prepedit revision. This -will leave the repository with multiple heads. At this point, all data is saved. -The system then tries to merge the heads with a merger that will fail if it cannot -resolve the conflict. If the merge succeeds then everything is ok. - -If that merge failed then there are conflicts. In this case, the current patch calls -merge again with a merger that inserts conflict markers. It commits this new -revision with conflict markers to the repository. It then returns the text to the -user for cleanup. This is less neat than it could be, in that a conflict marked -revision gets committed to the repository. diff --git a/doc/about_rcs_backends/discussion.mdwn b/doc/about_rcs_backends/discussion.mdwn deleted file mode 100644 index cedbaaa20..000000000 --- a/doc/about_rcs_backends/discussion.mdwn +++ /dev/null @@ -1,9 +0,0 @@ -## [[git]] - -I'm currently spending some thoughts on how to extend the -ikiwiki git infrastructure to allow for the two repositories -to be on different machines. Has someone else already made -such thoughts? --[[tschwinge]] - -> Okay, I got this working. I'll test and experiment some -> more and then document it in here. --[[tschwinge]] diff --git a/doc/bugs/Monotone_rcs_support.mdwn b/doc/bugs/Monotone_rcs_support.mdwn index 9514472ee..11f93f11b 100644 --- a/doc/bugs/Monotone_rcs_support.mdwn +++ b/doc/bugs/Monotone_rcs_support.mdwn @@ -1,6 +1,6 @@ #Ikiwiki plugin for the Monotone revision control system. -I've just made a patch to the ikiwiki code that allows it to use the [Monotone](http://monotone.ca/) revision control system. It is available at: +I've just made a patch to the ikiwiki code that allows it to use the [[rcs/Monotone]] revision control system. It is available at: diff --git a/doc/bugs/ikiwiki.setup_require_blank_rcs_to_work_as_cgi_only.mdwn b/doc/bugs/ikiwiki.setup_require_blank_rcs_to_work_as_cgi_only.mdwn index dde6e96d3..8ac6eeb09 100644 --- a/doc/bugs/ikiwiki.setup_require_blank_rcs_to_work_as_cgi_only.mdwn +++ b/doc/bugs/ikiwiki.setup_require_blank_rcs_to_work_as_cgi_only.mdwn @@ -24,7 +24,7 @@ Should it be documented ? >> push changes back. What I do is use svk, which is a distributed RCS based on svn, edit using text editors on my >> laptop, and periodically `svk push` up to the server, which triggers a rebuild on the server. I think [[Joey]] >> works this way too, but I'm not sure. If you don't like editing pages "by hand" then maybe you should look at ->> [[git]] or [[mercurial]] -- they should theoretically allow you to run apache on a working copy which is itself +>> [[rcs/git]] or [[rcs/mercurial]] -- they should theoretically allow you to run apache on a working copy which is itself >> a branch of a working copy running on another machine, but I haven't used them so I don't know. --Ethan >>> Well, by hand editing is just what I'm making sometime. it's just using subversion, in fact. diff --git a/doc/css_market.mdwn b/doc/css_market.mdwn index ded86c7f1..937b90c50 100644 --- a/doc/css_market.mdwn +++ b/doc/css_market.mdwn @@ -11,7 +11,7 @@ files..) * **[[css_market/kirkambar.css]]**, contributed by [[Roktas]]. This far from perfect stylesheet follows a [Gitweb](http://www.kernel.org/git/?p=git/git.git;a=tree;f=gitweb) - like theme, so it may provide a consistent look'n feel along with the [[git]] backend. ;-) + like theme, so it may provide a consistent look'n feel along with the [[rcs/git]] backend. ;-) You can see it in action on [kirkambar](http://kirkambar.net/) (Turkish content). [[meta stylesheet="kirkambar"]] diff --git a/doc/features.mdwn b/doc/features.mdwn index 0ecd1f7f3..a879d7237 100644 --- a/doc/features.mdwn +++ b/doc/features.mdwn @@ -9,10 +9,8 @@ lazy, it's because a real RCS is a good thing to have, and there are advantages to using one that are not possible with a standard wiki. Instead of editing pages in a stupid web form, you can use vim and commit -changes via [[Subversion]]. Or work disconnected using svk and push your -changes out when you come online. Or use [[git]], [[tla]], or [[mercurial]] -to work in a distributed fashion all the time. (It's also possible to -[[plugins/write]] a plugin to support other systems.) +changes via [[Subversion|rcs/svn]], [[rcs/git]], or any of a number of other +[[Revision_Control_Systems|rcs]]. ikiwiki can be run from a [[post-commit]] hook to update your wiki immediately whenever you commit a change using the RCS. diff --git a/doc/git.mdwn b/doc/git.mdwn deleted file mode 100644 index eeb05d5f2..000000000 --- a/doc/git.mdwn +++ /dev/null @@ -1,7 +0,0 @@ -[[meta title="Git"]] - -[Git](http://git.or.cz) is a distributed revison control system originally developed for the Linux kernel. Ikiwiki supports storing a wiki in git. - -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. \ No newline at end of file diff --git a/doc/ikiwikiusers.mdwn b/doc/ikiwikiusers.mdwn index 804f4e9c4..d7ea8b758 100644 --- a/doc/ikiwikiusers.mdwn +++ b/doc/ikiwikiusers.mdwn @@ -6,7 +6,7 @@ Projects * [Planet Debian upstream](http://updo.debian.net/) * The [ion window manager homepage](http://modeemi.fi/~tuomov/ion/) * [Debian Mentors wiki](http://jameswestby.net/mentors/) -* [LinuxWorld.com's monkey.linuxworld.com contributor wiki](http://monkey.linuxworld.com/) ([[Git]] backend) +* [LinuxWorld.com's monkey.linuxworld.com contributor wiki](http://monkey.linuxworld.com/) ([[rcs/Git]] backend) * The [Sparse wiki](http://kernel.org/pub/linux/kernel/people/josh/sparse). * [The BSD Associate Admin Book Project](http://bsdwiki.reedmedia.net/) * The [maildirman wiki](http://svcs.cs.pdx.edu/maildirman) @@ -18,7 +18,7 @@ Projects * [debian-community.org](http://debian-community.org/) * The [cairo graphics library](http://cairographics.org/) website. * [Nouvelles Informations Positives Libres community](http://wiki.nipl.net/) -* The [Portland State Aerospace Society](http://psas.pdx.edu) website. Converted from a combination of TWiki and MoinMoin to ikiwiki, including full history ([[Git]] backend). +* The [Portland State Aerospace Society](http://psas.pdx.edu) website. Converted from a combination of TWiki and MoinMoin to ikiwiki, including full history ([[rcs/Git]] backend). Personal sites and blogs ======================== @@ -37,7 +37,7 @@ Personal sites and blogs * [Christian Aichinger's homepage](http://greek0.net/) * [Ben A'Lee's homepage](http://bmalee.eu/~bma/) * [Adam Shand's homepage](http://adam.shand.net/iki/) -* [Recai Oktaş's homepage](http://kirkambar.net/) (uses [[Git]] backend, Turkish language only). +* [Recai Oktaş's homepage](http://kirkambar.net/) (uses [[rcs/Git]] backend, Turkish language only). * [Hess family wiki](http://kitenet.net/~family/) * [Stefano Zacchiroli's blog](http://www.bononia.it/~zack/blog/) * [Taquiones: Victor Moral's personal website in Spanish](http://taquiones.net) diff --git a/doc/index.mdwn b/doc/index.mdwn index 9d1110772..c89b0aa94 100644 --- a/doc/index.mdwn +++ b/doc/index.mdwn @@ -1,8 +1,8 @@ -Ikiwiki is a **wiki compiler**. It converts wiki pages -into HTML pages suitable for publishing on a website. Ikiwiki stores -pages and history in a revision control system such as [[Subversion]] -or [[Git]]. There are many other [[features]], including support for -[[blogging|blog]], as well as a large array of [[plugins]]. +Ikiwiki is a **wiki compiler**. It converts wiki pages into HTML pages +suitable for publishing on a website. Ikiwiki stores pages and history in a +[[revision_control_system|rcs]] such as [[rcs/Subversion]] or [[rcs/Git]]. +There are many other [[features]], including support for [[blogging|blog]], +as well as a large array of [[plugins]]. [[template id=links]] diff --git a/doc/install.mdwn b/doc/install.mdwn index f408e0af1..6ef81ea0c 100644 --- a/doc/install.mdwn +++ b/doc/install.mdwn @@ -14,8 +14,6 @@ installed, and also uses the following perl modules if available: [[cpan XML::Feed]], [[cpan File::MimeInfo]], [[cpan Locale::gettext]] (version 1.04 or newer). -The [[tla]] support also needs the [[cpan MailTools]] perl module. - Various [[plugins]] use other libraries and utlities; see their individual documentation for details. diff --git a/doc/mercurial.mdwn b/doc/mercurial.mdwn deleted file mode 100644 index 5eaae1997..000000000 --- a/doc/mercurial.mdwn +++ /dev/null @@ -1,8 +0,0 @@ -[Mercurial](http://selenic.com/mercurial) is a distributed revison control -system developed by Matt Mackall. Ikiwiki supports storing a wiki in a -mercurial repository. - -Ikiwiki can run as a post-update hook to update a wiki whenever commits -come in. When running as a [[cgi]] with Mercurial, ikiwiki automatically -commits edited pages, and uses the Mercurial history to generate the -[[RecentChanges]] page. diff --git a/doc/monotone.mdwn b/doc/monotone.mdwn deleted file mode 100644 index d68eb1ed5..000000000 --- a/doc/monotone.mdwn +++ /dev/null @@ -1,7 +0,0 @@ -[monotone](http://monotone.ca/) is a distributed revision control system. -Ikiwiki supports storing a wiki in tla. - -This requires the Monotone perl module from the monotone contrib/ directory -to be installed. In particlar, it needs version 0.03 or higher of that module. -It is available from the monotone source repository at: - diff --git a/doc/plugins/write.mdwn b/doc/plugins/write.mdwn index bbe047d33..7166d15f4 100644 --- a/doc/plugins/write.mdwn +++ b/doc/plugins/write.mdwn @@ -474,15 +474,15 @@ rendered to. ## RCS plugins -ikiwiki's support for revision control systems also uses pluggable perl -modules. These are in the `IkiWiki::RCS` namespace, for example +ikiwiki's support for [[revision_control_systems|rcs]] also uses pluggable +perl modules. These are in the `IkiWiki::RCS` namespace, for example `IkiWiki::RCS::svn`. Each RCS plugin must support all the `IkiWiki::rcs_*` functions. See IkiWiki::RCS::Stub for the full list of functions. It's ok if `rcs_getctime` does nothing except for throwing an error. -See [[about_RCS_backends]] for some more info. +See [[RCS_details|rcs/details]] for some more info. ## PageSpec plugins diff --git a/doc/post-commit.mdwn b/doc/post-commit.mdwn index 84375dad0..5178df6e6 100644 --- a/doc/post-commit.mdwn +++ b/doc/post-commit.mdwn @@ -1,6 +1,7 @@ -A post-commit hook is run every time you commit a change to your -[[subversion]] (or [[git]] or [[mercurial]]) repository. To make the wiki be updated each -time a commit is made, it can be run from (or as) a post-commit hook. +If your wiki is kept in [[revision control|rcs]], a post-commit hook is run +every time you commit a change to your repository. To make the wiki be +updated each time a commit is made, it can be run from (or as) a +post-commit hook. The best way to run ikiwiki in a post-commit hook is using a wrapper, which ikiwiki is usually configured to generate using a setup file. diff --git a/doc/rcs/details.mdwn b/doc/rcs/details.mdwn new file mode 100644 index 000000000..b9b3c7ead --- /dev/null +++ b/doc/rcs/details.mdwn @@ -0,0 +1,223 @@ +A few bits about the RCS backends + +[[toc ]] + +## Terminology + +``web-edit'' means that a page is edited by using the web (CGI) interface +as opposed to using a editor and the RCS interface. + + +## [[svn]] + +Subversion was the first RCS to be supported by ikiwiki. + +### How does it work internally? + +Master repository M. + +RCS commits from the outside are installed into M. + +There is a working copy of M (a checkout of M): W. + +HTML is generated from W. rcs_update() will update from M to W. + +CGI operates on W. rcs_commit() will commit from W to M. + +For all the gory details of how ikiwiki handles this behind the scenes, +see [[commit-internals]]. + +You browse and web-edit the wiki on W. + +W "belongs" to ikiwiki and should not be edited directly. + + +## [darcs](http://darcs.net/) (not yet included) + +Support for using darcs as a backend is being worked on by [Thomas +Schwinge](mailto:tschwinge@gnu.org), although development is on hold curretly. +There is a patch in [[todo/darcs]]. + +### How will it work internally? + +``Master'' repository R1. + +RCS commits from the outside are installed into R1. + +HTML is generated from R1. HTML is automatically generated (by using a +``post-hook'') each time a new change is installed into R1. It follows +that rcs_update() is not needed. + +There is a working copy of R1: R2. + +CGI operates on R2. rcs_commit() will push from R2 to R1. + +You browse the wiki on R1 and web-edit it on R2. This means for example +that R2 needs to be updated from R1 if you are going to web-edit a page, +as the user otherwise might be irritated otherwise... + +How do changes get from R1 to R2? Currently only internally in +rcs\_commit(). Is rcs\_prepedit() suitable? + +It follows that the HTML rendering and the CGI handling can be completely +separated parts in ikiwiki. + +What repository should [[RecentChanges]] and [[History]] work on? R1? + +#### Rationale for doing it differently than in the Subversion case + +darcs is a distributed RCS, which means that every checkout of a +repository is equal to the repository it was checked-out from. There is +no forced hierarchy. + +R1 is nevertheless called the master repository. It's used for +collecting all the changes and publishing them: on the one hand via the +rendered HTML and on the other via the standard darcs RCS interface. + +R2, the repository the CGI operates on, is just a checkout of R1 and +doesn't really differ from the other checkouts that people will branch +off from R1. + +(To be continued.) + +#### Another possible approach + +Here's what I (tuomov) think, would be a “cleaner” approach: + + 1. Upon starting to edit, Ikiwiki gets a copy of the page, and `darcs changes --context`. + This context _and_ the present version of the page are stored in as the “version” of the + page in a hidden control of the HTML. + Thus the HTML includes all that is needed to generate a patch wrt. to the state of the + repository at the time the edit was started. This is of course all that darcs needs. + 2. Once the user is done with editing, _Ikiwiki generates a patch bundle_ for darcs. + This should be easy with existing `Text::Diff` or somesuch modules, as the Web edits + only concern single files. The reason why the old version of the page is stored in + the HTML (possibly compressed) is that the diff can be generated. + 3. Now this patch bundle is applied with `darcs apply`, or sent by email for moderation… + there are many possibilities. + +This approach avoids some of the problems of concurrent edits that the previous one may have, +although there may be conflicts, which may or may not propagate to the displayed web page. +(Unfortunately there is not an option to `darcs apply` to generate some sort of ‘confliction resolution +bundle’.) Also, only one repository is needed, as it is never directly modified +by Ikiwiki. + +This approach might be applicable to other distributed VCSs as well, although they're not as oriented +towards transmitting changes with standalone patch bundles (often by email) as darcs is. + +> The mercurial plugin seems to just use one repo and edit it directly - is +> there some reason that's okay there but not for darcs? I agree with tuomov +> that having just the one repo would be preferable; the point of a dvcs is +> that there's no difference between one repo and another. I've got a +> darcs.pm based on mercurial.pm, that's almost usable... --bma + +>> IMHO it comes down to whatever works well for a given RCS. Seems like +>> the darcs approach _could_ be done with most any distributed system, but +>> it might be overkill for some (or all?) While there is the incomplete darcs +>> plugin in [[todo/darcs]], if you submit one that's complete, I will +>> probably accept it into ikiwiki.. --[[Joey]] + +## [[Git]] + +Regarding the Git support, Recai says: + +I have been testing it for the past few days and it seems satisfactory. I +haven't observed any race condition regarding the concurrent blog commits +and it handles merge conflicts gracefully as far as I can see. + +As you may notice from the patch size, GIT support is not so trivial to +implement (for me, at least). Being a fairly fresh code base it has some +bugs. It also has some drawbacks (especially wrt merge which was the hard +part). GIT doesn't have a similar functionality like 'svn merge -rOLD:NEW +FILE' (please see the relevant comment in mergepast for more details), so I +had to invent an ugly hack just for the purpose. + +By design, Git backend uses a "master-clone" repository pair approach in contrast +to the single repository approach (here, _clone_ may be considered as the working +copy of a fictious web user). Even though a single repository implementation is +possible, it somewhat increases the code complexity of backend (I couldn't figure +out a uniform method which doesn't depend on the prefered repository model, yet). +By exploiting the fact that the master repo and _web user_'s repo (`srcdir`) are all +on the same local machine, I suggest to create the latter with the "`git clone -l -s`" +command to save disk space. + +Note that, as a rule of thumb, you should always put the rcs wrapper (`post-update`) +into the master repository (`.git/hooks/`) as can be noticed in the Git wrappers of +the sample [[ikiwiki.setup]]. + +## [[Mercurial]] + +The Mercurial backend is still in a early phase, so it may not be mature +enough, but it should be simple to understand and use. + +As Mercurial is a distributed RCS, it lacks the distinction between +repository and working copy (every wc is a repo). + +This means that the Mercurial backend uses directly the repository as +working copy (the master M and the working copy W described in the svn +example are the same thing). + +You only need to specify 'srcdir' (the repository M) and 'destdir' (where +the HTML will be generated). + +Master repository M. + +RCS commit from the outside are installed into M. + +M is directly used as working copy (M is also W). + +HTML is generated from the working copy in M. rcs_update() will update +to the last committed revision in M (the same as 'hg update'). +If you use an 'update' hook you can generate automatically the HTML +in the destination directory each time 'hg update' is called. + +CGI operates on M. rcs_commit() will commit directly in M. + +If you have any question or suggestion about the Mercurial backend +please refer to [Emanuele](http://nerd.ocracy.org/em/) + +## [[tla]] + +## rcs + +There is a patch that needs a bit of work linked to from [[todo/rcs]]. + +## [[Monotone]] + +In normal use, monotone has a local database as well as a workspace/working copy. +In ikiwiki terms, the local database takes the role of the master repository, and +the srcdir is the workspace. As all monotone workspaces point to a default +database, there is no need to tell ikiwiki explicitly about the "master" database. It +will know. + +The backend currently supports normal committing and getting the history of the page. +To understand the parallel commit approach, you need to understand monotone's +approach to conflicts: + +Monotone allows multiple micro-branches in the database. There is a command, +`mtn merge`, that takes the heads of all these branches and merges them back together +(turning the tree of branches into a dag). Conflicts in monotone (at time of writing) +need to be resolved interactively during this merge process. +It is important to note that having multiple heads is not an error condition in a +monotone database. This condition will occur in normal use. In this case +'update' will choose a head if it can, or complain and tell the user to merge. + +For the ikiwiki plugin, the monotone ikiwiki plugin borrows some ideas from the svn ikiwiki plugin. +On prepedit() we record the revision that this change is based on (I'll refer to this as the prepedit revision). When the web user +saves the page, we check if that is still the current revision. If it is, then we commit. +If it isn't then we check to see if there were any changes by anyone else to the file +we're editing while we've been editing (a diff bewteen the prepedit revision and the current rev). +If there were no changes to the file we're editing then we commit as normal. + +It is only if there have been parallel changes to the file we're trying to commit that +things get hairy. In this case the current approach is to +commit the web changes as a branch from the prepedit revision. This +will leave the repository with multiple heads. At this point, all data is saved. +The system then tries to merge the heads with a merger that will fail if it cannot +resolve the conflict. If the merge succeeds then everything is ok. + +If that merge failed then there are conflicts. In this case, the current code calls +merge again with a merger that inserts conflict markers. It commits this new +revision with conflict markers to the repository. It then returns the text to the +user for cleanup. This is less neat than it could be, in that a conflict marked +revision gets committed to the repository. diff --git a/doc/rcs/git.mdwn b/doc/rcs/git.mdwn new file mode 100644 index 000000000..eeb05d5f2 --- /dev/null +++ b/doc/rcs/git.mdwn @@ -0,0 +1,7 @@ +[[meta title="Git"]] + +[Git](http://git.or.cz) is a distributed revison control system originally developed for the Linux kernel. Ikiwiki supports storing a wiki in git. + +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. \ No newline at end of file diff --git a/doc/rcs/mercurial.mdwn b/doc/rcs/mercurial.mdwn new file mode 100644 index 000000000..5eaae1997 --- /dev/null +++ b/doc/rcs/mercurial.mdwn @@ -0,0 +1,8 @@ +[Mercurial](http://selenic.com/mercurial) is a distributed revison control +system developed by Matt Mackall. Ikiwiki supports storing a wiki in a +mercurial repository. + +Ikiwiki can run as a post-update hook to update a wiki whenever commits +come in. When running as a [[cgi]] with Mercurial, ikiwiki automatically +commits edited pages, and uses the Mercurial history to generate the +[[RecentChanges]] page. diff --git a/doc/rcs/monotone.mdwn b/doc/rcs/monotone.mdwn new file mode 100644 index 000000000..d68eb1ed5 --- /dev/null +++ b/doc/rcs/monotone.mdwn @@ -0,0 +1,7 @@ +[monotone](http://monotone.ca/) is a distributed revision control system. +Ikiwiki supports storing a wiki in tla. + +This requires the Monotone perl module from the monotone contrib/ directory +to be installed. In particlar, it needs version 0.03 or higher of that module. +It is available from the monotone source repository at: + diff --git a/doc/rcs/svn.mdwn b/doc/rcs/svn.mdwn new file mode 100644 index 000000000..cd35511c0 --- /dev/null +++ b/doc/rcs/svn.mdwn @@ -0,0 +1,9 @@ +[Subversion](http://subversion.tigris.org/) is a revision control system. While ikiwiki is relatively +independent of the underlying revision control system, and can easily be +used without one, using it with Subversion is recommended since it's how +the author uses it. + +Ikiwiki can run as a [[post-commit]] hook to update a wiki whenever commits +come in. When running as a [[cgi]] with Subversion, ikiwiki automatically +commits edited pages to the subversion repostory, and uses the Subversion +log to generate the [[RecentChanges]] page. diff --git a/doc/rcs/svn/discussion.mdwn b/doc/rcs/svn/discussion.mdwn new file mode 100644 index 000000000..426735182 --- /dev/null +++ b/doc/rcs/svn/discussion.mdwn @@ -0,0 +1,13 @@ +If the user interrupts the page loading during the running of `svn commit`, +the repository will be left in an inconsistent state. The probability of +this happening increases with the size of the repository and the number of +plugins installed, because these both affect how long the post-commit hook +takes to run. (The core issue, I guess, is that we're abusing the concept +of a "working copy" by giving everybody the same one). Here are the main +solutions that I can see: (1) CGI queues commits so that a single process +can act upon them sequentially, or (2) optionally divorce the `ikiwiki +--refresh` from the `svn commit` so that commits happen faster. -- [[Ben]] + +I'm not aware of web servers, at least apache, killing cgi processes when +the user stops a page load. If this is happening ikiwiki should be able to +avoid it by blocking whatever signal is causing it to terminate. --[[Joey]] diff --git a/doc/rcs/tla.mdwn b/doc/rcs/tla.mdwn new file mode 100644 index 000000000..cafd9b49b --- /dev/null +++ b/doc/rcs/tla.mdwn @@ -0,0 +1,10 @@ +[tla](http://wiki.gnuarch.org/) is an implementation of the +[GNU](http://www.gnu.org/) [Arch](http://www.gnuarch.org/) revision control +system. Ikiwiki supports storing a wiki in tla. + +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 +log to generate the [[RecentChanges]] page. + +Note that the tla support needs the [[cpan MailTools]] perl module. diff --git a/doc/recentchanges.mdwn b/doc/recentchanges.mdwn index 9613f2480..2e67f02e7 100644 --- a/doc/recentchanges.mdwn +++ b/doc/recentchanges.mdwn @@ -1,4 +1,3 @@ -ikiwiki generates the list of recent changes by examining the -history of the revision control system ([[Subversion]], etc) that the wiki -is configured to use. You have to have [[CGI]] set up for this feature to be -enabled. +ikiwiki generates the list of recent changes by examining the history of +the [[revision_control_system|rcs]] that the wiki is configured to use. You +have to have [[CGI]] set up for this feature to be enabled. diff --git a/doc/subversion.mdwn b/doc/subversion.mdwn deleted file mode 100644 index 7cb994c1a..000000000 --- a/doc/subversion.mdwn +++ /dev/null @@ -1,9 +0,0 @@ -[Subversion](http://subversion.tigris.org/) is a revision control system. While ikiwiki is relatively -independent of the underlying revision control system, and can easily be -used without one, using it with Subversion is recommended since it's how -the author uses it. ([[Git]] is another option.) - -Ikiwiki can run as a [[post-commit]] hook to update a wiki whenever commits -come in. When running as a [[cgi]] with Subversion, ikiwiki automatically -commits edited pages to the subversion repostory, and uses the Subversion -log to generate the [[RecentChanges]] page. diff --git a/doc/subversion/discussion.mdwn b/doc/subversion/discussion.mdwn deleted file mode 100644 index 426735182..000000000 --- a/doc/subversion/discussion.mdwn +++ /dev/null @@ -1,13 +0,0 @@ -If the user interrupts the page loading during the running of `svn commit`, -the repository will be left in an inconsistent state. The probability of -this happening increases with the size of the repository and the number of -plugins installed, because these both affect how long the post-commit hook -takes to run. (The core issue, I guess, is that we're abusing the concept -of a "working copy" by giving everybody the same one). Here are the main -solutions that I can see: (1) CGI queues commits so that a single process -can act upon them sequentially, or (2) optionally divorce the `ikiwiki ---refresh` from the `svn commit` so that commits happen faster. -- [[Ben]] - -I'm not aware of web servers, at least apache, killing cgi processes when -the user stops a page load. If this is happening ikiwiki should be able to -avoid it by blocking whatever signal is causing it to terminate. --[[Joey]] diff --git a/doc/tla.mdwn b/doc/tla.mdwn deleted file mode 100644 index 4c2b9227c..000000000 --- a/doc/tla.mdwn +++ /dev/null @@ -1,8 +0,0 @@ -[tla](http://wiki.gnuarch.org/) is an implementation of the -[GNU](http://www.gnu.org/) [Arch](http://www.gnuarch.org/) revision control -system. Ikiwiki supports storing a wiki in tla. - -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 -log to generate the [[RecentChanges]] page. diff --git a/doc/todo/git_attribution.mdwn b/doc/todo/git_attribution.mdwn index 21f5ed287..b75cad671 100644 --- a/doc/todo/git_attribution.mdwn +++ b/doc/todo/git_attribution.mdwn @@ -1 +1 @@ -When run with the [[Git]] backend, ikiwiki should use `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` rather than munging the commit message. Depending on the semantics you want to imply (does a web edit constitute a commit by the user or by the script?), it could also set `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` to the same values. --[[JoshTriplett]] \ No newline at end of file +When run with the [[rcs/Git]] backend, ikiwiki should use `GIT_AUTHOR_NAME` and `GIT_AUTHOR_EMAIL` rather than munging the commit message. Depending on the semantics you want to imply (does a web edit constitute a commit by the user or by the script?), it could also set `GIT_COMMITTER_NAME` and `GIT_COMMITTER_EMAIL` to the same values. --[[JoshTriplett]] diff --git a/doc/usage.mdwn b/doc/usage.mdwn index aba213f21..17be02044 100644 --- a/doc/usage.mdwn +++ b/doc/usage.mdwn @@ -130,20 +130,12 @@ configuration options of their own. Enable email notification of commits. This should be used when running ikiwiki as a [[post-commit]] hook. -* --rcs=svn, --no-rcs +* --rcs=svn|git|.., --no-rcs - Enable or disable use of a revision control system. + Enable or disable use of a [[revision_control_system|rcs]]. - If you use svn, the `source` directory is assumed to be - a [[Subversion]] working copy. - - If you use git, the `source` directory is assumed to be a clone of the - [[git]] repository. - - If you use tla, the `source` directory is assumed to be a tla import. - - If you use mercurial, the `source` directory is assumed to be the - [[mercurial]] repository. + The `source` directory will be assumed to be a working copy, or clone, or + whatever the revision control system you select uses. In [[CGI]] mode, with a revision control system enabled, pages edited via the web will be committed. Also, the [[RecentChanges]] link will be placed @@ -154,7 +146,7 @@ configuration options of their own. * --svnrepo /svn/wiki Specify the location of the svn repository for the wiki. This is required - for using --notify with [[Subversion]]. + for using --notify with [[Subversion|rcs/svn]]. * --svnpath trunk