source: release-kits/shared/ant-tasks/svnant/doc/types.html@ 17129

Last change on this file since 17129 was 17129, checked in by oranfry, 16 years ago

a newer version of svnant
File size: 13.8 KB
Line 
1<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<html xmlns:ant="http://www.fiset.ca/ant-docs/v1" xmlns:html="http://www.w3.org/1999/xhtml" xmlns="http://www.w3.org/1999/xhtml">
4<head>
5<META HTTP-EQUIV="CONTENT-TYPE" CONTENT="text/html; charset=windows-1252"/>
6<title>Svn Types</title>
7<META HTTP-EQUIV="Content-Language" CONTENT="en-us"/>
8<style type="text/css">
9
10 body {
11 font: 80% Verdana, Arial, Helvetica, sans-serif;
12 margin: 5px; padding: 0;
13 /* background: rgb(95%,95%,80%); */
14 color: black;
15 }
16 h1 {
17 font-size: 200%; letter-spacing: 3px;
18 margin-bottom: 1em;
19 padding: 0.66em 0 0.33em 1em;
20 background: rgb(85%,85%,70%);
21 }
22 h2 {
23 background: rgb(90%,90%,80%);
24 }
25 h3 {
26 background-color: rgb(95%,95%,85%);
27 }
28 .sample {
29 font-family: Courier, "Courier New", monospace;
30 background-color: #f3f1f4;
31 }
32 div.sample {
33 margin-left: 10px;
34 margin-right: 10px;
35 padding-top: 3px;
36 padding-bottom: 3px;
37 padding-left: 3px;
38 padding-right: 3px;
39 border:1px dashed black;
40 width: 80%;
41 }
42 table.params {
43 width: 80%;
44 border: 1px solid gray;
45 margin-bottom:1em;
46 }
47 th.params, td.params {
48 padding: 0 0.5em;
49 border-left: 1px solid #DDD;
50 border-bottom: 1px solid #DDD;
51 font: 70%
52 }
53 th.params {
54
55 }
56 table.toc {
57 width: 80%;
58 border: 1px solid gray;
59 margin-bottom:1em;
60 }
61 td.toc {
62 padding: 0 0.5em;
63 border: none
64 font: 70%
65 }
66 table.type {
67 width: 80%;
68 border: none;
69 margin-bottom:1em;
70 }
71 th.type, td.type {
72 text-align: left;
73 padding: 0 0.5em;
74 border: none
75 font: 70%
76 }
77 th.type {
78 font-weight: bold;
79 }
80
81 </style>
82</head>
83<body lang="en-US" dir="LTR">
84<h1>Svn Types</h1>
85<h2>Table of Content</h2>
86<table class="toc">
87<tbody class="toc">
88<tr class="toc">
89<td class="toc">
90<a href="#svnFileSet">svnFileSet</a>
91</td>
92<td class="toc">FileSet replacement that operates on list of files obtained from Subversion.</td>
93</tr>
94</tbody>
95</table>
96<h2>Introduction</h2>
97<ant:introduction xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
98 <p>
99 This document describes the type extensions that svn-ant brings to Ant. To use those types,
100 you must first obtain a copy of svnant.jar, add it to the classpath of your ant project
101 and define the types. Fortunately, there is a resource file, within the distributed JAR file,
102 and all those steps can be accomplished with the following code:
103 <div class="sample">
104<pre class="sample">
105
106&lt;path id="svnant.classpath"&gt;
107 &lt;pathelement location="${svnant.dir}/lib/svnant.jar" /&gt;
108 &lt;pathelement location="${svnant.dir}/lib/svnClientAdapter.jar" /&gt;
109&lt;/path&gt;
110
111&lt;typedef resource="svntypes.xml" classpathref="project.classpath"/&gt;
112
113 </pre>
114</div>
115 </p>
116 <p>
117 If you are upgrading from an earlier version of svnAnt, and the following line was used
118 in your <i>build.xml</i> file, then replace it with the ones above.
119 <div class="sample">
120<pre class="sample">
121
122&lt;taskdef resource="svntask.properties" classpathref="svnant.classpath"/&gt;
123
124 </pre>
125</div>
126 </p>
127 <h3>
128<a name="bindings">Bindings</a>
129</h3>
130 <p>
131 All types offer two parameters: <b>javahl</b> and <b>svnkit</b>. Those parameters
132 are booleans, which means their values can be set to either <b>true</b> or <b>false</b>.
133 If not specified, those parameters are assumed to be set (true). These two parameters are used
134 to select which client is used to access Subversion.
135 </p>
136 <p>
137 There are three clients used by svnAnt to access Subversion:
138 <ul>
139 <li>JavaHL;</li>
140 <li>SVNKit; and,</li>
141 <li>Command Line Interface.</li>
142 </ul>
143 To better understand the difference between those three clients, please refer to
144 documentation on <b>svnClientAdapter.jar</b>.
145 </p>
146 <p>
147 The property <b>javahl</b> is considered only if the javahl libraries are available. Similarly,
148 the property <b>svnkit</b> is considered only if SVNKit is present. Finally, <b>javahl</b>
149 takes precedence over <b>svnkit</b>.
150 </p>
151 <p>
152 To better illustrate the previous paragraph, use the following steps:
153 <ol>
154 <li>If <b>javahl</b> is <i>true</i> and JavaHL bindings are available, then JavaHL is used.</li>
155 <li>If <b>svnkit</b> is <i>true</i> and SVNKit is present, then SVNKit is used.</li>
156 <li>If the two previous tests failed, for any reason, then the Command Line Interface is used.</li>
157 </ol>
158 </p>
159 </ant:introduction>
160<h1>
161<a name="">svnFileSet</a>
162</h1>
163<p>FileSet replacement that operates on list of files obtained from Subversion.</p>
164<table class="type">
165<tbody class="type">
166<tr class="type">
167<th class="type">Implementation:</th>
168<td class="type">org.tigris.subclipse.svnant.SvnFileSet</td>
169</tr>
170</tbody>
171</table>
172<h2>Parameters</h2>
173<table class="params">
174<tr class="params">
175<th class="params">Attribute</th>
176<th class="params">Description</th>
177<th class="params">Required</th>
178</tr>
179<tr class="params">
180<td class="params">dir</td>
181<td class="params">
182<ant:description xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
183 Specifies the root directory used by the file set. It should specify
184 a directory managed by Subversion.
185 </ant:description>
186</td>
187<td class="params">
188<ant:required xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
189 Either dir or file must be specified
190 </ant:required>
191</td>
192</tr>
193<tr class="params">
194<td class="params">file</td>
195<td class="params">
196<ant:description xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
197 If used, specifies a fileset that contains a single file.
198 </ant:description>
199</td>
200<td class="params">
201<ant:required xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
202 Either dir or file must be specified
203 </ant:required>
204</td>
205</tr>
206<tr class="params">
207<td class="params">includes</td>
208<td class="params">
209<ant:description xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
210 Comma-seperated or space-separated list of patterns, which describe files that are
211 included. If this attribute if not specified, then all files are included.
212 </ant:description>
213</td>
214<td class="params">
215<ant:required xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
216 No
217 </ant:required>
218</td>
219</tr>
220<tr class="params">
221<td class="params">excludes</td>
222<td class="params">
223<ant:description xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
224 Comma-seperated or space-separated list of patterns, which describe files that are
225 excluded. If this attribute if not specified, then no files are excluded.
226 </ant:description>
227</td>
228<td class="params">
229<ant:required xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
230 No
231 </ant:required>
232</td>
233</tr>
234<tr class="params">
235<td class="params">javahl</td>
236<td class="params">
237<ant:description xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
238 If set, instructs the use of JavaHL bindings, if available.
239 Set to <b>false</b> to use command line client interface to subversion.
240 Defaults to true. See <a href="#bindings">note</a> for more details.
241 </ant:description>
242</td>
243<td class="params">
244<ant:required xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
245 No
246 </ant:required>
247</td>
248</tr>
249<tr class="params">
250<td class="params">svnkit</td>
251<td class="params">
252<ant:description xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
253 If set, instructs the use of SVNKit bindings, if available.
254 Set to <b>false</b> to use command line client interface to subversion.
255 Defaults to true. See <a href="#bindings">note</a> for more details.
256 </ant:description>
257</td>
258<td class="params">
259<ant:required xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
260 No
261 </ant:required>
262</td>
263</tr>
264</table>
265<h2>Nested Types</h2>
266<h3>exclude</h3>
267 The type svnFileSet can include the nested type 'exclude', similar to a classic FileSet.
268 <h3>include</h3>
269 The type svnFileSet can include the nested type 'include', similar to a classic FileSet.
270 <h3>patternSet</h3>
271 The type svnFileSet can include the nested type 'patternSet', similar to a classic FileSet.
272 <h3>selector</h3>
273 The type svnFileSet can include the any file selector, such as <b xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">contains</b>, <b xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">date</b>
274 <b xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">size</b>, or any <a xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" href="selectors.html">file selector defined by svn-ant</a>
275 <h2>Description</h2>
276 <p xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
277 This type implements a FileSet. Instances of FileSet are used in tasks that operates on a number of files. The files
278 selected by a FileSet can be tailored by a number of patterns and selectors. More information about file sets is available
279 with the Ant documentation.
280 </p>
281 <p xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
282 The motivation with creating a replacement FileSet that is based on Subversion was to have the ability of creating
283 sets of files that include deleted and missing files. In fact, the classic fileset operates only on files that are reported
284 by the file system and can not predict deleted and missing files. Furthermore, there are useful commands that can be performed
285 on deleted and missing files, such as 'revert', 'delete', 'update' and others.
286 </p>
287 <p xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
288 At the present time, <b>svnFileSet</b> is experimental. It supports selectors but it does not yet accept any patterns
289 (include, exclude). Those enhancments are to come later.
290 </p>
291 <p xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
292 <b>svnFileSet</b> can be used within any svn-ant task that supports a nested file sets. It can also be used in any task
293 that is based on a file set. If you have a problem using <b>svnFileSet</b> within a task that works well with the classic
294 fileset, then report the problem to the author of the task. However, for the time being, there is a work around your
295 problem. Instead of using a <b>svnFileSet</b> directly in the targeted task, use it indirectly via a classic fileset and
296 a reference. For example, if ANT complains about a task similar to the following:
297 <div class="sample">
298<pre class="sample">
299
300&lt;target name="example"&gt;
301 &lt;mkdir dir="test"/&gt;
302 &lt;copy todir="test"&gt;
303 &lt;svnFileSet dir="workingcopy"&gt;
304 &lt;svnAdded/&gt;
305 &lt;/svnFileSet&gt;
306 &lt;/copy&gt;
307&lt;/target&gt;
308
309 </pre>
310</div>
311
312 you can rewrite it, using a reference, as:
313
314 <div class="sample">
315<pre class="sample">
316
317&lt;target name="example"&gt;
318 &lt;svnFileSet id="svnFileSetId_1" dir="workingcopy"&gt;
319 &lt;svnAdded/&gt;
320 &lt;/svnFileSet&gt;
321 &lt;mkdir dir="test"/&gt;
322 &lt;copy todir="test"&gt;
323 &lt;fileset refid="svnFileSetId_1"/&gt;
324 &lt;/copy&gt;
325&lt;/target&gt;
326
327 </pre>
328</div>
329 </p>
330 <p xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
331 If you are the author of a fileset-based task and that you can not understand
332 why your task does not accept <b>svnFileSet</b> while it works perfectly well
333 with the classic fileset, here is a thing you can check. If your task
334 accepts instances of FileSet with a method similar to:
335 <div class="sample">
336<pre class="sample">
337
338public void addFileset(FileSet set) {
339 ...
340}
341
342 </pre>
343</div>
344 then adding the following method should fix the problem:
345 <div class="sample">
346<pre class="sample">
347
348public void add(FileSet set) {
349 addFileSet(set);
350}
351
352 </pre>
353</div>
354 </p>
355 <h3 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">Examples</h3>
356 <p xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
357 The following ant script can be used to remove all missing files from the associated repository:
358 <div class="sample">
359<pre class="sample">
360
361&lt;svn&gt;
362 &lt;delete&gt;
363 &lt;svnFileSet dir="workingcopy"&gt;
364 &lt;svnMissing/&gt;
365 &lt;/svnFileSet&gt;
366 &lt;/delete&gt;
367 &lt;commit
368 dir="workingcopy"
369 message="automatically removing missing files"/&gt;
370&lt;/svn&gt;
371
372 </pre>
373</div>
374 </p>
375 <p xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
376 The following ant script can be used to add all new files to the associated repository:
377 <div class="sample">
378<pre class="sample">
379
380&lt;svn&gt;
381 &lt;add&gt;
382 &lt;svnFileSet dir="workingcopy"&gt;
383 &lt;svnUnversioned/&gt;
384 &lt;/svnFileSet&gt;
385 &lt;/add&gt;
386 &lt;commit
387 dir="workingcopy"
388 message="automatically adding files"/&gt;
389&lt;/svn&gt;
390
391 </pre>
392</div>
393 </p>
394 <p xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
395 The following ant script can be used to restore all deleted files:
396 <div class="sample">
397<pre class="sample">
398
399&lt;svn&gt;
400 &lt;revert&gt;
401 &lt;svnFileSet dir="workingcopy"&gt;
402 &lt;svnDeleted/&gt;
403 &lt;/svnFileSet&gt;
404 &lt;/revert&gt;
405&lt;/svn&gt;
406
407 </pre>
408</div>
409 </p>
410 <p xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance">
411 If, in the previous example, you wanted svn-ant to use the command line adapter:
412 <div class="sample">
413<pre class="sample">
414
415&lt;svn javahl="false" svnkit="false"&gt;
416 &lt;revert&gt;
417 &lt;svnFileSet
418 dir="workingcopy"
419 javahl="false"
420 svnkit="false"&gt;
421 &lt;svnDeleted
422 javahl="false"
423 svnkit="false"/&gt;
424 &lt;/svnFileSet&gt;
425 &lt;/revert&gt;
426&lt;/svn&gt;
427
428 </pre>
429</div>
430 </p>
431 </body>
432</html>
Note: See TracBrowser for help on using the repository browser.