1 | This file documents Subversion's use of the WebDAV/DeltaV protocol. |
---|
2 | |
---|
3 | |
---|
4 | IMPORTANT RFCs and LINKS |
---|
5 | ======================== |
---|
6 | |
---|
7 | * RFC 2518 (WebDAV) |
---|
8 | |
---|
9 | * RFC 3253 (DeltaV) |
---|
10 | |
---|
11 | * Subversion's limited uses of DeltaV, as well as interoperability |
---|
12 | issues, are explained in the "WebDAV" appendix of the free |
---|
13 | Subversion book (at http://svnbook.red-bean.com) |
---|
14 | |
---|
15 | |
---|
16 | |
---|
17 | |
---|
18 | HTTP METHODS USED, indexed by svn commands that access network |
---|
19 | ============================================================== |
---|
20 | |
---|
21 | |
---|
22 | Read Commands : (OPTIONS, PROPFIND, GET, REPORT) |
---|
23 | ------------- |
---|
24 | |
---|
25 | Most commands have to resolve peg-revisions before starting: |
---|
26 | |
---|
27 | * -r X foo@Y REPORT ('get-locations') |
---|
28 | |
---|
29 | ...if an old server doesn't support 'get-locations' report, the |
---|
30 | client traces history using the 'log-report' instead. |
---|
31 | |
---|
32 | And any command which has to convert a date to a revision: |
---|
33 | |
---|
34 | * -r {DATE} REPORT ('dated-rev-report') |
---|
35 | |
---|
36 | |
---|
37 | The following group of commands all use the custom 'update-report' |
---|
38 | request, which is just a fancy way of driving svn_repos_dir_delta(): |
---|
39 | |
---|
40 | * svn checkout / svn export / svn update: |
---|
41 | (do_update RA interface) |
---|
42 | |
---|
43 | ra_neon: PROPFIND, REPORT ('update-report' w/send-all) |
---|
44 | |
---|
45 | ra_serf: PROPFIND, REPORT ('update-report') |
---|
46 | ... then many PROPFIND/GETs on many parallel connections |
---|
47 | |
---|
48 | svn update only ('merge-info-report') |
---|
49 | |
---|
50 | * svn switch: OPTIONS, PROPFIND, REPORT ('update-report', |
---|
51 | 'merge-info-report') |
---|
52 | |
---|
53 | * svn diff: OPTIONS, PROPFIND, REPORT ('update-report') |
---|
54 | ... then many GETs |
---|
55 | |
---|
56 | * svn merge: OPTIONS, PROPFIND, REPORT ('update-report', |
---|
57 | 'merge-info-report') |
---|
58 | ... then many GETs |
---|
59 | |
---|
60 | * svn status -u: OPTIONS, PROPFIND, REPORT ('update-report' and |
---|
61 | 'get-locks-report') |
---|
62 | |
---|
63 | * svn cp URL wc: OPTIONS, PROPFIND, REPORT ('update-report') |
---|
64 | (this is just like checkout) |
---|
65 | |
---|
66 | |
---|
67 | And these guys are left over: |
---|
68 | |
---|
69 | * svn log: OPTIONS, PROPFIND, REPORT ('log-report') |
---|
70 | |
---|
71 | * svn blame: OPTIONS, PROPFIND, REPORT ('file-revs-report') |
---|
72 | [older clients use GET |
---|
73 | and different REPORT] ('log-report') |
---|
74 | |
---|
75 | * svn ls: PROPFIND |
---|
76 | |
---|
77 | * svn ls -v: PROPFIND, REPORT ('get-locks-report') |
---|
78 | |
---|
79 | * svn cat: PROPFIND, GET |
---|
80 | |
---|
81 | * svn info URL: PROPFIND |
---|
82 | |
---|
83 | * svn plist URL: PROPFIND |
---|
84 | |
---|
85 | * svn pget URL: PROPFIND |
---|
86 | |
---|
87 | |
---|
88 | |
---|
89 | |
---|
90 | Write Commands : (MKACTIVITY, PROPPATCH, PUT, CHECKOUT, MKCOL, MOVE, |
---|
91 | -------------- COPY, DELETE, LOCK, UNLOCK, MERGE) |
---|
92 | |
---|
93 | With the exception of LOCK/UNLOCK, every write command performs some |
---|
94 | sort of DeltaV commit operation. In DeltaV, a commit always starts |
---|
95 | by creating a transaction (MKACTIVITY), applies a log message |
---|
96 | (PROPPATCH), does some other write methods, and then ends by |
---|
97 | committing the transaction (MERGE). If the MERGE fails, the client |
---|
98 | may try to remove the transaction with a DELETE. |
---|
99 | |
---|
100 | * svn commit: |
---|
101 | ra_neon: OPTIONS, PROPFIND, MKACTIVITY, |
---|
102 | {CHECKOUT, COPY, MOVE, DELETE, PROPPATCH, PUT, MKCOL}, |
---|
103 | MERGE (DELETE) |
---|
104 | |
---|
105 | ra_serf: OPTIONS to acquire activity collection set |
---|
106 | (no major MKACTIVITY to a unique UUID relative to activity set |
---|
107 | differences) PROPFIND to get what we think our baseline is |
---|
108 | CHECKOUT of baseline revision into activity |
---|
109 | Setting log: PROPPATCH on root directory |
---|
110 | Delete a file: CHECKOUT file / DELETE |
---|
111 | Add a dir: MKCOL |
---|
112 | Add a file: CHECKOUT parent dirs / PUT raw-file |
---|
113 | Edit a file: CHECKOUT file / PUT svndiff stream |
---|
114 | End commit: MERGE activity, DELETE activity |
---|
115 | |
---|
116 | * svn import: OPTIONS, PROPFIND, MKACTIVITY, |
---|
117 | {PROPPATCH, PUT, MKCOL}, |
---|
118 | MERGE (DELETE) |
---|
119 | |
---|
120 | * svn lock: PROPFIND, LOCK |
---|
121 | |
---|
122 | * svn unlock: PROPFIND, UNLOCK |
---|
123 | |
---|
124 | * svn cp URL URL: OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH, |
---|
125 | COPY, MERGE. (DELETE) |
---|
126 | |
---|
127 | * svn mv URL URL: OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH, |
---|
128 | COPY, DELETE, MERGE. (DELETE) |
---|
129 | |
---|
130 | * svn rm URL: OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH, DELETE, MERGE. |
---|
131 | |
---|
132 | * svn mkdir URL: OPTIONS, PROPFIND, MKACTIVITY, PROPPATCH, MKCOL, MERGE. |
---|
133 | |
---|
134 | * svn pset --revprop: PROPPATCH |
---|
135 | |
---|
136 | Remembering Our Location |
---|
137 | ======================== |
---|
138 | |
---|
139 | For a file in our WC, both ra_serf and ra_neon will store the checked-in href |
---|
140 | (where the original text-base and properties can be found) in the |
---|
141 | svn:wc:ra_dav:version-url wcprop. |
---|
142 | |
---|
143 | Example property: |
---|
144 | svn:wc:ra_dav:version-url -> /repos/test/!svn/ver/2/httpd/configure |
---|
145 | |
---|
146 | GET |
---|
147 | === |
---|
148 | |
---|
149 | ra_serf |
---|
150 | ------- |
---|
151 | |
---|
152 | For a file that a WC already has when it wants to do an update, ra_serf will |
---|
153 | send two extra headers: |
---|
154 | |
---|
155 | X-SVN-VR-Base: <checked-in href of locally-present file> |
---|
156 | Accept-Encoding: svndiff1;q=0.9,svndiff;q=0.8 |
---|
157 | |
---|
158 | The server may choose not to return svndiff content but return full-text. |
---|
159 | |
---|
160 | (ra_neon has this same functionality, but is largely just dead code.) |
---|
161 | |
---|
162 | Example |
---|
163 | ------- |
---|
164 | |
---|
165 | Request: |
---|
166 | |
---|
167 | GET /repos/test/!svn/ver/3/httpd/configure HTTP/1.1 |
---|
168 | X-SVN-VR-Base: /repos/test/!svn/ver/2/httpd/configure |
---|
169 | Accept-Encoding: svndiff1;q=0.9,svndiff;q=0.8 |
---|
170 | |
---|
171 | Response: |
---|
172 | |
---|
173 | HTTP/1.1 200 OK |
---|
174 | ETag: "3//httpd/configure" |
---|
175 | Vary: Accept-Encoding |
---|
176 | Content-Type: application/vnd.svn-svndiff |
---|
177 | |
---|
178 | ...svn-svndiff stream that can be passed to svn_txdelta_parse_svndiff... |
---|
179 | |
---|
180 | Custom REPORTs |
---|
181 | ============== |
---|
182 | |
---|
183 | We use a bunch of custom reports, here's a little info on what they look like. |
---|
184 | |
---|
185 | update-report |
---|
186 | ------------- |
---|
187 | |
---|
188 | Purpose: Present what we have in our WC to the server and let it tell us what |
---|
189 | has changed. Has an optional 'send-all' attribute that will include |
---|
190 | the text-deltas in base64-encoding inline to the XML REPORT response. |
---|
191 | |
---|
192 | Target URL: Base VCC URL |
---|
193 | Example: REPORT /repos/test/!svn/vcc/default |
---|
194 | |
---|
195 | Note: ra_serf will not set the send-all attribute to the update-report. It |
---|
196 | will instead take the returned D:checked-in href and do a pipelined |
---|
197 | PROPFIND / GET on that resource. |
---|
198 | |
---|
199 | Note: If a client had a previous revision, it would not send the 'start-empty' |
---|
200 | attribute to entry. |
---|
201 | |
---|
202 | Request: |
---|
203 | |
---|
204 | <S:update-report send-all="true" xmlns:S="svn:"> |
---|
205 | <S:src-path>http://localhost:8080/repos/test/httpd/support</S:src-path> |
---|
206 | <S:target-revision>2</S:target-revision> |
---|
207 | <S:entry rev="2" start-empty="true"></S:entry> |
---|
208 | </S:update-report> |
---|
209 | |
---|
210 | Response: |
---|
211 | |
---|
212 | <S:update-report xmlns:S="svn:" xmlns:V="..." xmlns:D="DAV:" send-all="true"> |
---|
213 | <S:target-revision rev="2"/> |
---|
214 | <S:open-directory rev="2"> |
---|
215 | <D:checked-in> |
---|
216 | <D:href>/repos/test/!svn/ver/2/httpd/support</D:href> |
---|
217 | </D:checked-in> |
---|
218 | <S:set-prop name="svn:entry:committed-rev">2</S:set-prop> |
---|
219 | ... more set props ... |
---|
220 | <S:add-file name="ab.c"> |
---|
221 | <D:checked-in> |
---|
222 | <D:href>/repos/test/!svn/ver/2/httpd/support/ab.c</D:href> |
---|
223 | </D:checked-in> |
---|
224 | <S:set-prop name="svn:entry:committed-rev">2</S:set-prop> |
---|
225 | ... more set props for the file ... |
---|
226 | <S:txdelta>...base64-encoded file content...</S:txdelta> |
---|
227 | </S:add-file> |
---|
228 | <S:add-directory name="os" bc-url="/repos/test/!svn/bc/2/httpd/os"> |
---|
229 | <D:checked-in> |
---|
230 | <D:href>/repos/test/!svn/ver/2/httpd/os</D:href> |
---|
231 | </D:checked-in> |
---|
232 | ...directory contents... |
---|
233 | </S:add-directory> |
---|
234 | </S:open-directory> |
---|
235 | </S:update-report> |
---|
236 | |
---|
237 | dated-rev-report |
---|
238 | ---------------- |
---|
239 | |
---|
240 | Purpose: Get the revision associated with a particular date. |
---|
241 | |
---|
242 | Target URL: VCC URL for repos. |
---|
243 | |
---|
244 | Request: |
---|
245 | |
---|
246 | <S:dated-rev-report xmlns:S="svn:" xmlns:D="DAV:"> |
---|
247 | <D:creationdate>2005-12-07T13:06:26.034802Z</D:creationdate> |
---|
248 | </S:dated-rev-report> |
---|
249 | |
---|
250 | Response: |
---|
251 | |
---|
252 | <S:dated-rev-report xmlns:S="svn:" xmlns:D="DAV:"> |
---|
253 | <D:version-name>4747</D:version-name> |
---|
254 | </S:dated-rev-report> |
---|
255 | |
---|
256 | get-locks-report |
---|
257 | ---------------- |
---|
258 | |
---|
259 | Purpose: Get the locks associated with a particular resource. |
---|
260 | |
---|
261 | Target URL: URL of item we're getting the locks for |
---|
262 | |
---|
263 | Request: |
---|
264 | |
---|
265 | <S:get-locks-report xmlns:S="svn"> |
---|
266 | </S:get-locks-report> |
---|
267 | |
---|
268 | Response: |
---|
269 | |
---|
270 | <S:get-locks-report xmlns:S="svn"> |
---|
271 | <S:lock> |
---|
272 | <S:path>/foo/bar/baz</S:path> |
---|
273 | <S:token>opaquelocktoken:706689a6-8cef-0310-9809-fb7545cbd44e</S:token> |
---|
274 | <S:owner>fred</S:owner> |
---|
275 | <S:comment encoding="base64">ET39IGCB93LL4M</S:comment> |
---|
276 | <S:creationdate>2005-02-07T14:17:08Z</S:creationdate> |
---|
277 | <S:expirationdate>2005-02-08T14:17:08Z</S:expirationdate> |
---|
278 | </S:lock> |
---|
279 | </S:get-locks-report> |
---|
280 | |
---|
281 | get-locations |
---|
282 | ------------- |
---|
283 | |
---|
284 | Purpose: Get the location of a path appearing in a particular revision. |
---|
285 | |
---|
286 | Target URL: Current baseline collection for a directory plus relative paths. |
---|
287 | Example: REPORT /repos/test/!svn/bc/5/httpd |
---|
288 | |
---|
289 | Request: |
---|
290 | |
---|
291 | <S:get-locations xmlns:S="svn:"> |
---|
292 | <S:path></S:path> |
---|
293 | <S:peg-revision>5</S:peg-revision> |
---|
294 | <S:location-revision>1</S:location-revision> |
---|
295 | </S:get-locations> |
---|
296 | |
---|
297 | Response: |
---|
298 | |
---|
299 | <?xml version="1.0" encoding="utf-8"?> |
---|
300 | <S:get-locations-report xmlns:S="svn:" xmlns:D="DAV:"> |
---|
301 | <S:location rev="1" path="/httpd"/> |
---|
302 | </S:get-locations-report> |
---|
303 | |
---|
304 | log-report |
---|
305 | ---------- |
---|
306 | |
---|
307 | Purpose: Retrieve the log for a portion of the repository. |
---|
308 | |
---|
309 | Target URL: Current baseline collection for a directory plus relative paths. |
---|
310 | Example: REPORT /repos/test/!svn/bc/5/httpd/support |
---|
311 | |
---|
312 | Request: |
---|
313 | |
---|
314 | <S:log-report xmlns:S="svn:"> |
---|
315 | <S:start-revision>2</S:start-revision> |
---|
316 | <S:end-revision>2</S:end-revision> |
---|
317 | <S:limit>1</S:limit> (optional) |
---|
318 | <S:discover-changed-paths/> (optional) |
---|
319 | <S:strict-node-history/> (optional) |
---|
320 | <S:include-merged-revisions/> (optional) |
---|
321 | <S:revprop>REVPROP</S:revprop>... | <S:all-revprops/> | <S:no-revprops/> |
---|
322 | ('revprop', 'all-revprops', and 'no-revprops' are all optional) |
---|
323 | <S:path></S:path>... (optional) |
---|
324 | </S:log-report> |
---|
325 | |
---|
326 | Response: |
---|
327 | |
---|
328 | <?xml version="1.0" encoding="utf-8"?> |
---|
329 | <S:log-report xmlns:S="svn:" xmlns:D="DAV:"> |
---|
330 | <S:log-item> |
---|
331 | <D:version-name>2</D:version-name> |
---|
332 | <S:creator-displayname>bob</S:creator-displayname> |
---|
333 | <S:date>2006-02-27T18:44:26.149336Z</S:date> |
---|
334 | <D:comment>Add doo-hickey</D:comment> |
---|
335 | <S:revprop name="REVPROP">value</S:revprop>... (optional) |
---|
336 | <S:has-children/> (optional) |
---|
337 | <S:added-path( copyfrom-path="PATH" copyfrom-rev="REVNUM">PATH</S:added-path>... (optional) |
---|
338 | <S:replaced-path( copyfrom-path="PATH" copyfrom-rev="REVNUM">PATH</S:replaced-path>... (optional) |
---|
339 | <S:deleted-path>PATH</S:deleted-path>... (optional) |
---|
340 | <S:modified-path>PATH</S:modified-path>... (optional) |
---|
341 | </S:log-item> |
---|
342 | ...multiple log-items for each returned revision... |
---|
343 | </S:log-report> |
---|
344 | |
---|
345 | mergeinfo-report |
---|
346 | ---------------- |
---|
347 | |
---|
348 | Purpose: Retrieve the merge history for a portion of the repository |
---|
349 | (e.g. a set of paths) at a particular revision. |
---|
350 | |
---|
351 | Target URL: URL of item we're getting merge info for. |
---|
352 | |
---|
353 | Note: <S:inherit> is a representation of the svn_mergeinfo_inheritance_t |
---|
354 | struct and can have the values 'explicit', 'inherited', or |
---|
355 | 'nearest-ancestor'. The default value is 'explicit' if <S:inherit> |
---|
356 | is not present or has any other value than those three. |
---|
357 | |
---|
358 | <S:include-descendants> represents the 'include_descendants' |
---|
359 | boolean argument to svn_ra_get_mergeinfo(). It can be 'yes' or |
---|
360 | 'no'; the default value is 'no' (mapping to FALSE). |
---|
361 | |
---|
362 | Request: |
---|
363 | |
---|
364 | <S:mergeinfo-report xmlns:S="svn:"> |
---|
365 | <S:revision>1</S:revision> |
---|
366 | <S:inherit>inherited</S:inherit> |
---|
367 | <S:include-descendants>yes</S:include-descendants> |
---|
368 | <S:path>/A/B/E/alpha</S:path> |
---|
369 | </S:mergeinfo-report> |
---|
370 | |
---|
371 | Response: |
---|
372 | |
---|
373 | <?xml version="1.0" encoding="utf-8"?> |
---|
374 | <S:mergeinfo-report xmlns:S="svn:" xmlns:D="DAV:"> |
---|
375 | <S:mergeinfo-item> |
---|
376 | <S:mergeinfo-path>/A_COPY/B/E</S:mergeinfo-path> |
---|
377 | <S:mergeinfo-info>/A/B/E:1,3-4</S:mergeinfo-info> |
---|
378 | </S:mergeinfo-item> |
---|
379 | </S:mergeinfo-report> |
---|