ikiwiki (3.20130711) unstable; urgency=low
[ikiwiki.git] / doc / rcs / details.mdwn
1 A few bits about the RCS backends
2
3 [[!toc ]]
4
5 ## Terminology
6
7 ``web-edit'' means that a page is edited by using the web (CGI) interface
8 as opposed to using a editor and the RCS interface.
9
10
11 ## [[svn]]
12
13 Subversion was the first RCS to be supported by ikiwiki.
14
15 ### How does it work internally?
16
17 Master repository M.
18
19 RCS commits from the outside are installed into M.
20
21 There is a working copy of M (a checkout of M): W.
22
23 HTML is generated from W.  rcs_update() will update from M to W.
24
25 CGI operates on W.  rcs_commit() will commit from W to M.
26
27 For all the gory details of how ikiwiki handles this behind the scenes,
28 see [[commit-internals]].
29
30 You browse and web-edit the wiki on W.
31
32 W "belongs" to ikiwiki and should not be edited directly.
33
34
35 ## [[darcs]]
36
37 Regarding the repository layout: There are two darcs repositories. One is the `srcdir`, the other we'll call `master`.
38
39 *  HTML is generated from `srcdir`.
40 *  CGI edits happen in `srcdir`.
41 *  The backend pulls updates from `master` into `srcdir`, i.e. darcs commits should happen to `master`.
42 *  `master` calls ikiwiki (through a wrapper) in its apply posthook, i.e. `master/_darcs/prefs/defaults` should look like this:
43
44         apply posthook ikiwrap
45         apply run-posthook
46
47 *  The backend pushes CGI edits from `srcdir` back into `master` (triggering the apply hook).
48 *  The working copies in `srcdir` and `master` should *not* be touched by the user, only by the CGI or darcs, respectively.
49
50 ## [[Git]]
51
52 Regarding the Git support, Recai says:
53
54 I have been testing it for the past few days and it seems satisfactory.  I
55 haven't observed any race condition regarding the concurrent blog commits
56 and it handles merge conflicts gracefully as far as I can see.
57
58 (After about a year, git support is nearly as solid as subversion support --[[Joey]])
59
60 As you may notice from the patch size, GIT support is not so trivial to
61 implement (for me, at least). It has some drawbacks (especially wrt merge
62 which was the hard part).  GIT doesn't have a similar functionality like
63 'svn merge -rOLD:NEW FILE' (please see the relevant comment in `_merge_past`
64 for more details), so I had to invent an ugly hack just for the purpose.
65
66 > I was looking at this, and WRT the problem of uncommitted local changes,
67 > it seems to me you could just git-stash them now that git-stash exists.
68 > I think it didn't when you first added the git support.. --[[Joey]]
69
70
71 >> Yes,  git-stash had not existed before.  What about sth like below?  It
72 >> seems to work (I haven't given much thought on the specific implementation
73 details).  --[[roktas]]
74
75 >>          # create test files
76 >>          cd /tmp
77 >>          seq 6 >page
78 >>          cat page
79 >>          1
80 >>          2
81 >>          3
82 >>          4
83 >>          5
84 >>          6
85 >>          sed -e 's/2/2ME/' page >page.me # my changes
86 >>          cat page
87 >>          1
88 >>          2ME
89 >>          3
90 >>          4
91 >>          5
92 >>          6
93 >>          sed -e 's/5/5SOMEONE/' page >page.someone # someone's changes
94 >>          cat page
95 >>          1
96 >>          2
97 >>          3
98 >>          4
99 >>          5SOMEONE
100 >>          6
101 >>
102 >>          # create a test repository
103 >>          mkdir t
104 >>          cd t
105 >>          cp ../page .
106 >>          git init
107 >>          git add .
108 >>          git commit -m init
109 >>
110 >>          # save the current HEAD
111 >>          ME=$(git rev-list HEAD -- page)
112 >>          $EDITOR page # assume that I'm starting to edit page via web
113 >>
114 >>          # simulates someone's concurrent commit
115 >>          cp ../page.someone page
116 >>          git commit -m someone -- page
117 >>
118 >>          # My editing session ended, the resulting content is in page.me
119 >>          cp ../page.me page
120 >>          cat page
121 >>          1
122 >>          2ME
123 >>          3
124 >>          4
125 >>          5
126 >>          6
127 >>
128 >>          # let's start to save my uncommitted changes
129 >>          git stash clear
130 >>          git stash save "changes by me"
131 >>          # we've reached a clean state
132 >>          cat page
133 >>          1
134 >>          2
135 >>          3
136 >>          4
137 >>          5SOMEONE
138 >>          6
139 >>
140 >>          # roll-back to the $ME state
141 >>          git reset --soft $ME
142 >>          # now, the file is marked as modified
143 >>          git stash save "changes by someone"
144 >>
145 >>          # now, we're at the $ME state
146 >>          cat page
147 >>          1
148 >>          2
149 >>          3
150 >>          4
151 >>          5
152 >>          6
153 >>          git stash list
154 >>          stash@{0}: On master: changes by someone
155 >>          stash@{1}: On master: changes by me
156 >>
157 >>          # first apply my changes
158 >>          git stash apply stash@{1}
159 >>          cat page
160 >>          1
161 >>          2ME
162 >>          3
163 >>          4
164 >>          5
165 >>          6
166 >>          # ... and commit
167 >>          git commit -m me -- page
168 >>
169 >>          # apply someone's changes
170 >>          git stash apply stash@{0}
171 >>          cat page
172 >>          1
173 >>          2ME
174 >>          3
175 >>          4
176 >>          5SOMEONE
177 >>          6
178 >>          # ... and commit
179 >>          git commit -m me+someone -- page
180
181 By design, Git backend uses a "master-clone" repository pair approach in contrast
182 to the single repository approach (here, _clone_ may be considered as the working
183 copy of a fictious web user).  Even though a single repository implementation is
184 possible, it somewhat increases the code complexity of backend (I couldn't figure
185 out a uniform method which doesn't depend on the prefered repository model, yet).
186 By exploiting the fact that the master repo and _web user_'s repo (`srcdir`) are all
187 on the same local machine, I suggest to create the latter with the "`git clone -l -s`"
188 command to save disk space.
189
190 Note that, as a rule of thumb, you should always put the rcs wrapper (`post-update`)
191 into the master repository (`.git/hooks/`).
192
193 Here is how a web edit works with ikiwiki and git:
194
195 * ikiwiki cgi modifies the page source in the clone
196 * git-commit in the clone
197 * git push origin master, pushes the commit from the clone to the master repo
198 * the master repo's post-update hook notices this update, and runs ikiwiki
199 * ikiwiki notices the modifies page source, and compiles it
200
201 Here is a how a commit from a remote repository works:
202
203 * git-commit in the remote repository
204 * git-push, pushes the commit to the master repo on the server
205 * (Optionally, the master repo's pre-receive hook runs, and checks that the
206   update only modifies files that the pushing user is allowed to update. 
207   If not, it aborts the receive.)
208 * the master repo's post-update hook notices this update, and runs ikiwiki
209 * ikiwiki notices the modifies page source, and compiles it
210
211 ## [[Mercurial]]
212
213 The Mercurial backend is still in a early phase, so it may not be mature 
214 enough, but it should be simple to understand and use.
215
216 As Mercurial is a distributed RCS, it lacks the distinction between 
217 repository and working copy (every wc is a repo).
218
219 This means that the Mercurial backend uses directly the repository as 
220 working copy (the master M and the working copy W described in the svn 
221 example are the same thing).
222
223 You only need to specify 'srcdir' (the repository M) and 'destdir' (where
224 the HTML will be generated).
225
226 Master repository M.
227
228 RCS commit from the outside are installed into M.
229
230 M is directly used as working copy (M is also W).
231
232 HTML is generated from the working copy in M. rcs_update() will update 
233 to the last committed revision in M (the same as 'hg update').
234 If you use an 'update' hook you can generate automatically the HTML
235 in the destination directory each time 'hg update' is called.
236
237 CGI operates on M. rcs_commit() will commit directly in M.
238
239 If you have any question or suggestion about the Mercurial backend 
240 please refer to [Emanuele](http://nerd.ocracy.org/em/)
241
242 ## [[tla]]
243
244 Nobody really understands how tla works. ;-)
245
246 ## rcs
247
248 There is a patch that needs a bit of work linked to from [[todo/rcs]].
249
250 ## [[Monotone]]
251
252 In normal use, monotone has a local database as well as a workspace/working copy.
253 In ikiwiki terms, the local database takes the role of the master repository, and
254 the srcdir is the workspace.  As all monotone workspaces point to a default
255 database, there is no need to tell ikiwiki explicitly about the "master" database.  It
256 will know.
257
258 The backend currently supports normal committing and getting the history of the page.
259 To understand the parallel commit approach, you need to understand monotone's
260 approach to conflicts:
261
262 Monotone allows multiple micro-branches in the database.  There is a command,
263 `mtn merge`, that takes the heads of all these branches and merges them back together
264 (turning the tree of branches into a dag).  Conflicts in monotone (at time of writing)
265 need to be resolved interactively during this merge process.
266 It is important to note that having multiple heads is not an error condition in a
267 monotone database.  This condition will occur in normal use.  In this case
268 'update' will choose a head if it can, or complain and tell the user to merge.
269
270 For the ikiwiki plugin, the monotone ikiwiki plugin borrows some ideas from the svn ikiwiki plugin.
271 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
272 saves the page, we check if that is still the current revision.  If it is, then we commit.
273 If it isn't then we check to see if there were any changes by anyone else to the file
274 we're editing while we've been editing (a diff bewteen the prepedit revision and the current rev).
275 If there were no changes to the file we're editing then we commit as normal.
276
277 It is only if there have been parallel changes to the file we're trying to commit that
278 things get hairy.  In this case the current approach is to
279 commit the web changes as a branch from the prepedit revision.  This
280 will leave the repository with multiple heads.  At this point, all data is saved.
281 The system then tries to merge the heads with a merger that will fail if it cannot
282 resolve the conflict.  If the merge succeeds then everything is ok.
283
284 If that merge failed then there are conflicts.  In this case, the current code calls
285 merge again with a merger that inserts conflict markers.  It commits this new
286 revision with conflict markers to the repository.  It then returns the text to the
287 user for cleanup.  This is less neat than it could be, in that a conflict marked
288 revision gets committed to the repository.
289
290 ## [[bzr]]
291
292 ## [[cvs]]