X-Git-Url: http://git.vanrenterghem.biz/git.ikiwiki.info.git/blobdiff_plain/89347d858619a764a2009c47909c6deb4c8d8ca6..de5cd1e12b2fa626344a183c509a88e29439f4e1:/doc/about_rcs_backends.mdwn diff --git a/doc/about_rcs_backends.mdwn b/doc/about_rcs_backends.mdwn index 764fece97..197f09394 100644 --- a/doc/about_rcs_backends.mdwn +++ b/doc/about_rcs_backends.mdwn @@ -1,16 +1,16 @@ -## A few bits about the RCS backends +# A few bits about the RCS backends -### Terminology +## 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]] -Subversion was that first RCS to be supported by ikiwiki. +Subversion was the first RCS to be supported by ikiwiki. -#### How does it work internally? +### How does it work internally? Master repository M. @@ -22,15 +22,18 @@ 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. -### [darcs](http://darcs.net/) (not yet included) +## [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). -#### How will it work internally? +### How will it work internally? ``Master'' repository R1. @@ -45,29 +48,77 @@ 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 the web-edit a page, +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? +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 +#### 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 the nevertheless called the master repository. It's used for +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 where CGI operates on, is just a checkout of R1 and +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.) + + +## [[Git]] (not yet included) + +A patch with full [Git](http://git.or.cz) support is at . Regarding the patch, 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. + +Some other notes: + +- There are two separate helper packages in git.pm. To keep things self + confined, I haven't split it up. + +- I've used a (mini) Debug.pm during the tests and made it a separate file + for the convenience of others. It relies on the "constant folding" + feature of Perl, so there shouldn't be a runtime penalty (at least this + is what the 'perl -MO=Deparse shows', haven't made a real benchmark). + +- rcs_notify() has not been implemented yet (I have noticed it after I + finished the main work). + +- GIT backend uses the gitweb for repository browsing (the counterpart of + ViewCVS). + +- There might be some subs in GIT name space which you may prefer to move to + the main code. + +- Due to the reasons explained in the code, I've written an rcs_invoke() + wrapper. May be there should be a better approach to reach the same + goal. + +- There are some parts which I may change in future, like using a global + rcs_fatal_error and the ugly error reporting code in _rcs_commit. + +- Documentation is missing. + +It works for me, but of course in the end, the final decision is yours (due +to mostly GIT quirks, the implementation is not clean as SVN). Feel free +to fix/delete/add whatever you want. Hope it doesn't have any serious bug.