You can not select more than 25 topics Topics must start with a chinese character,a letter or number, can include dashes ('-') and can be up to 35 characters long.

starteam.html 38 KiB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472473474475476477478479480481482483484485486487488489490491492493494495496497498499500501502503504505506507508509510511512513514515516517518519520521522523524525526527528529530531532533534535536537538539540541542543544545546547548549550551552553554555556557558559560561562563564565566567568569570571572573574575576577578579580581582583584585586587588589590591592593594595596597598599600601602603604605606607608609610611612613614615616617618619620621622623624625626627628629630631632633634635636637638639640641642643644645646647648649650651652653654655656657658659660661662663664665666667668669670671672673674675676677678679680681682683684685686687688689690691692693694695696697698699700701702703704705706707708709710711712713714715716717718719720721722723724725726727728729730731732733734735736737738739740741742743744745746747748749750751752753754755756757758759760761762763764765766767768769770771772773774775776777778779780781782783784785786787788789790791792793794795796797798799800801802803804805806807808809810811812813814815816817818819820821822823824825826827828829830831832833834835836837838839840841842843844845846847848849850851852853854855856857858859860861862863864865866867868869870871872873874875876877878879880881882883884885886887888889890891892893894895896897898899900901902903904905906907908909910911912913914915916917918919920921922923924925926927928929930931932933934935936937938939940941942943944945946947948949950951952953954955956957958959960961962963964965966967968969970971972973974975976
  1. <html>
  2. <head>
  3. <meta http-equiv="Content-Language" content="en-us">
  4. <title>StarTeam Tasks</title>
  5. </head>
  6. <body>
  7. <h1>StarTeam Support</h1>
  8. <ul>
  9. <li><a href="#stcheckout">STCheckout</a></li>
  10. <li><a href="#stcheckin">STCheckin</a></li>
  11. <li><a href="#stlabel">STLabel</a></li>
  12. <li><a href="#stlist">STList</a></li>
  13. <li><a href="#starteam"><i>StarTeam (deprecated) </i></a></li>
  14. </ul>
  15. <p>
  16. The StarTeam revision control system was recently acquired by Borland.
  17. These tasks make use of functions from the StarTeam API to work with that system.
  18. As a result they are only available to licensed users of StarTeam. You must have
  19. <CODE>starteam-sdk.jar</CODE> in your classpath to run these tasks.
  20. For more information about the StarTeam API and how to license it, see
  21. the <a href="http://www.borland.com/starteam/">Borland</a> web site.</p>
  22. <p>
  23. <em>All the StarTeam task names are in lower case.</em>
  24. </p>
  25. <h3>Important Note on Installation and Licensing:</h3>
  26. <p>
  27. <b>On Windows machines, the mere presence of <CODE>starteam-sdk.jar</CODE> on the classpath
  28. is not sufficient for getting these tasks to work properly.</b> These tasks also require a
  29. fully-installed and fully-licensed version of the StarGate Runtime. This is part
  30. of a StarTeam client installation or may be installed separately. The full client
  31. install is not required. In particular, the Windows path must include the directory where
  32. the StarGate Runtime <CODE>.dll</CODE> files are installed.
  33. </p><p>
  34. Earlier versions of Ant (prior to 1.5.2) did not have this restriction because they
  35. were not as dependent on the StarTeam runtime - which the newer versions use to access
  36. StarTeam file status information. The older versions lacked this important capability.
  37. </p>
  38. <hr></hr>
  39. <a name="common-params">
  40. <h2>Common Parameters for All Starteam Tasks</h2></a>
  41. <p>
  42. The following parameters, having to do with making the connection to a StarTeam project, are common to all the following tasks except the deprecated <i>StarTeam</i> task.
  43. </p>
  44. <table border="1" cellpadding="2" cellspacing="0">
  45. <tr>
  46. <td valign="top"><b>Attribute</b></td>
  47. <td valign="top"><b>Description</b></td>
  48. <td align="center" valign="top"><b>Required</b></td>
  49. </tr>
  50. <tr>
  51. <td valign="top">username</td>
  52. <td valign="top">The username of the account used to log in to the StarTeam server.</td>
  53. <td align="center" valign="top">yes</td>
  54. </tr>
  55. <tr>
  56. <td valign="top">password</td>
  57. <td valign="top">The password of the account used to log in to the StarTeam server.</td>
  58. <td align="center" valign="top">yes</td>
  59. </tr>
  60. <tr>
  61. <td valign="top">URL</td>
  62. <td valign="top">A string of the form <code>servername:portnum/project/view</code>
  63. which enables user to set all of these elements in one string. </td>
  64. <td align="center" valign="center"> Either this ...</td>
  65. </tr>
  66. <tr>
  67. <td valign="top">servername</td>
  68. <td valign="top">The name of the StarTeam server.</td>
  69. <td align="center" valign="center" rowspan = "4">... or <b>all four</b> of these must be defined.</td>
  70. </tr>
  71. <tr>
  72. <td valign="top">serverport</td>
  73. <td valign="top">The port number of the StarTeam server.</td>
  74. </tr>
  75. <tr>
  76. <td valign="top">projectname</td>
  77. <td valign="top">The name of the StarTeam project on which to operate.</td>
  78. </tr>
  79. <tr>
  80. <td valign="top">viewname</td>
  81. <td valign="top">The name of the view in the StarTeam project on which to operate.</td>
  82. </tr>
  83. </table>
  84. <hr></hr>
  85. <a name="stcheckout">
  86. <h2>STCheckout</h2></a>
  87. <h3>Description</h3>
  88. Checks out files from a StarTeam project.
  89. <p>
  90. The <i>includes</i> and <i>excludes</i> attributes function differently from
  91. other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
  92. </p>
  93. <h3>Parameters</h3>
  94. See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
  95. <table border="1" cellpadding="2" cellspacing="0">
  96. <tr>
  97. <td valign="top"><b>Attribute</b></td>
  98. <td valign="top"><b>Description</b></td>
  99. <td align="center" valign="top"><b>Required</b></td>
  100. </tr>
  101. <tr>
  102. <td valign="top">rootstarteamfolder</td>
  103. <td valign="top">The root of the subtree in the StarTeam repository from which to
  104. check out files. Defaults to the root folder of the view ('/').
  105. <b><i>If supplied, this should always be an "absolute" path, that is, it should begin with a '/'.
  106. Relative paths have little meaning in this context and confuse StarTeam.</i></b>
  107. </td>
  108. <td align="center" valign="top">no</td>
  109. </tr>
  110. <tr>
  111. <td valign="top">rootlocalfolder</td>
  112. <td valign="top">The local folder which will be the root of the tree to which files are checked out. If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used.
  113. </td>
  114. <td align="center" valign="top">no</td>
  115. </tr>
  116. <tr>
  117. <td valign="top">createworkingdirs</td>
  118. <td valign="top">creates local folders even when the corresponding StarTeam folder is empty. Defaults to "true".</td>
  119. <td align="center" valign="top">no</td>
  120. </tr>
  121. <tr>
  122. <td valign="top">deleteuncontrolled</td>
  123. <td valign="top">if true, any files NOT in StarTeam will be deleted. Defaults to "true".</td>
  124. <td align="center" valign="top">no</td>
  125. </tr>
  126. <tr>
  127. <td valign="top">includes</td>
  128. <td valign="top">Only check out files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
  129. <td align="center" valign="top">no</td>
  130. </tr>
  131. <tr>
  132. <td valign="top">excludes</td>
  133. <td valign="top">Do not check out files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
  134. <td align="center" valign="top">no</td>
  135. </tr>
  136. <tr>
  137. <td valign="top">label</td>
  138. <td valign="top">Check out files as of this label. The label must exist in starteam or an exception will be thrown.</td>
  139. <td align="center" valign="center" rowspan="2">Either or neither, but not both, may be specified. Neither <code>locked</code> or <code>unlocked</code> may be true if either <code>label</code> or <code>asofdate</code> is specified.</td>
  140. </tr>
  141. <tr>
  142. <td valign="top">asofdate</td>
  143. <td valign="top">Check out files as of this date. The date must
  144. be formatted in ISO8601 datetime
  145. (<code>yyyy-MM-dd'T'HH:mm:ss</code>), ISO8601
  146. date(<code>yyyy-MM-dd</code>) or a user-defined SimpleDateFormat
  147. defined in the <code>asofDateFormat</code> attribute. If the date
  148. is not parsable by the default or selected format, an exception
  149. will be thrown. <em>Since Ant 1.6.</em></td>
  150. </tr>
  151. <tr>
  152. <td valign="top">asofdateformat</td>
  153. <td valign="top">java.util.SimpleDateFormat compatible string used
  154. to parse the <code>asofdate</code> attribute. <em>Since Ant
  155. 1.6.</em></td>
  156. <td align="center" valign="top">no</td>
  157. </tr>
  158. <tr>
  159. <td valign="top">recursive</td>
  160. <td valign="top">Indicates if subfolders should be searched for files to check out. Defaults to "true".</td>
  161. <td align="center" valign="top">no</td>
  162. </tr>
  163. <tr>
  164. <td valign="top">forced</td>
  165. <td valign="top">If true, checkouts will occur regardless of the status
  166. that StarTeam is maintaining for the file. If false, status will be used to determine which files to check out. Defaults to "false".</td>
  167. <td align="center" valign="top">no</td>
  168. </tr>
  169. <tr>
  170. <td valign="top">locked</td>
  171. <td valign="top">If true, file will be locked against changes by other
  172. users. If false (default) has no effect.
  173. <td align="center" valign="center" rowspan="2">Either or neither, but not both, may be true. Neither may be true if a <code>label</code> or an <code>asofdate</code> is specified.</td>
  174. </tr>
  175. <tr>
  176. <td valign="top">unlocked</td>
  177. <td valign="top">If true, file will be unlocked so that other users may
  178. change it. This is a way to reverse changes that have not yet been checked in.
  179. If false (default) has no effect.</td>
  180. </tr>
  181. <tr>
  182. <td valign="top">userepositorytimestamp</td>
  183. <td valign="top">true means checked out files will get the repository timestamp.
  184. false(default) means the checked out files will be timestamped at the time
  185. of checkout.</td> <td align="center" valign="top">no</td>
  186. </tr>
  187. <tr>
  188. <td valign="top">preloadfileinformation</td>
  189. <td valign="top">The StarTeam server has the ability to preload file metadata for an
  190. entire tree prior to beginning action on that tree. Doing so can in some instances
  191. lead to substantially faster actions, particularly over large trees. Setting this
  192. to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>
  193. <td align="center" valign="top">no</td>
  194. </tr>
  195. <tr>
  196. <td valign="top">convertEOL</td>
  197. <td valign="top">If true, (default) all ascii files will have their end-of-line
  198. characters adjusted to that of the local machine on checkout. This is normally
  199. what you'd want but if for some reason you don't want that to happen, set it to false
  200. and the files will be checked out with whatever end-of-line characters are used on
  201. the server. </td>
  202. <td align="center" valign="top">no</td>
  203. </tr>
  204. </table>
  205. <h3>Examples</h3>
  206. <pre>
  207. &lt;stcheckout servername="STARTEAM"
  208. serverport="49201"
  209. projectname="AProject"
  210. viewname="AView"
  211. username="auser"
  212. password="secret"
  213. rootlocalfolder="C:\dev\buildtest\co"
  214. forced="true"
  215. /&gt;
  216. </pre>
  217. The minimum necessary to check out files out from a StarTeam server. This will
  218. check out all files in the <i>AView</i> view of the <i>AProject</i> project to
  219. <code>C:\dev\buildtest\co</code>. Empty folders in StarTeam will have local folders
  220. created for them and any non-StarTeam files found in the tree will be deleted.
  221. <pre>
  222. &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
  223. username="auser"
  224. password="secret"
  225. rootlocalfolder="C:\dev\buildtest\co"
  226. forced="true"
  227. /&gt;
  228. </pre>
  229. And this is a simpler way of accomplishing the same thing as the previous example, using the URL attribute.
  230. <br></br>
  231. <pre>
  232. &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
  233. username="auser"
  234. password="secret"
  235. rootlocalfolder="C:\dev\buildtest\co"
  236. rootstarteamfolder="\Dev"
  237. excludes="*.bak *.old"
  238. label="v2.6.001"
  239. forced="true"
  240. /&gt;
  241. </pre>
  242. This will check out all files from the <i>Dev</i> folder and below that do not
  243. end in <i>.bak</i> or <i>.old</i> with the label <i>v2.6.001</i>.
  244. <pre>
  245. &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
  246. username="auser"
  247. password="secret"
  248. rootlocalfolder="C:\dev\buildtest\co"
  249. includes="*.htm,*.html"
  250. excludes="index.*"
  251. forced="true"
  252. /&gt;
  253. </pre>
  254. This is an example of overlapping <i>includes</i> and <i>excludes</i> attributes. Because
  255. <i>excludes</i> takes precedence over <i>includes</i>, files named <code>index.html</code> will
  256. not be checked out by this command.
  257. <pre>
  258. &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
  259. username="auser"
  260. password="secret"
  261. rootlocalfolder="C:\dev\buildtest\co"
  262. includes="*.htm,*.html"
  263. excludes="index.*"
  264. forced="true"
  265. recursive="false"
  266. /&gt;
  267. </pre>
  268. This example is like the previous one, but will only check out files in
  269. C:\dev\buildtest\co, because of the turning off of the recursive attribute.
  270. <pre>
  271. &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
  272. username="auser"
  273. password="secret"
  274. rootstarteamfolder="src/java"
  275. rootlocalfolder="C:\dev\buildtest\co"
  276. forced="true"
  277. /&gt;
  278. </pre>
  279. <br></br>
  280. <pre>
  281. &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
  282. username="auser"
  283. password="secret"
  284. rootstarteamfolder="src/java"
  285. /&gt;
  286. </pre>
  287. <br></br>
  288. <pre>
  289. &lt;stcheckout URL="STARTEAM:49201/Aproject/AView"
  290. username="auser"
  291. password="secret"
  292. rootstarteamfolder="src/java"
  293. rootlocalfolder="C:\dev\buildtest\co\src\java"
  294. forced="true"
  295. /&gt;
  296. </pre>
  297. In the preceding three examples, assuming that the AProject project has a default folder of
  298. "C:\work\AProject", the first example will check out the tree of files rooted in the src/java folder of the AView view of the AProject in the StarTeam repository to a local tree rooted at C:\dev\buildtest\co,
  299. the second to a tree rooted at C:\work\AProject\src\java (since no <i>rootlocalfolder</i> is specified) and the third to a tree rooted at C:\dev\buildtest\co\src\java. Note also, that since the second example does not set "forced" true, only those files which the repository considers out-of-date will be checked out.
  300. <hr></hr>
  301. <a name="stcheckin">
  302. <h2>STCheckin</h2></a>
  303. <h3>Description</h3>
  304. Checks files into a StarTeam project. Optionally adds files and in the local tree that are not managed by the repository to its control.
  305. <p>
  306. The <i>includes</i> and <i>excludes</i> attributes function differently from
  307. other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
  308. </p>
  309. <h3>Parameters</h3>
  310. See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
  311. <table border="1" cellpadding="2" cellspacing="0">
  312. <tr>
  313. <td valign="top"><b>Attribute</b></td>
  314. <td valign="top"><b>Description</b></td>
  315. <td align="center" valign="top"><b>Required</b></td>
  316. </tr>
  317. <tr>
  318. <td valign="top">rootstarteamfolder</td>
  319. <td valign="top">The root of the subtree in the StarTeam repository into which to
  320. files will be checked. Defaults to the root folder of the view ('/').
  321. <b><i>If supplied, this should always be an "absolute" path, that is, it should begin with a '/'.
  322. Relative paths have little meaning in this context and confuse StarTeam.</i></b></td>
  323. <td align="center" valign="top">no</td>
  324. </tr>
  325. <tr>
  326. <td valign="top">rootlocalfolder</td>
  327. <td valign="top">The local folder which will be the root of the tree to which files are checked out. If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used. </td>
  328. <td align="center" valign="top">no</td>
  329. </tr>
  330. <tr>
  331. <td valign="top">comment</td>
  332. <td valign="top">Checkin comment to be saved with the file.</td>
  333. <td align="center" valign="top">no</td>
  334. </tr>
  335. <tr>
  336. <td valign="top">adduncontrolled</td>
  337. <td valign="top">if true, any files or folders NOT in StarTeam will be
  338. added to the repository. Defaults to "false".</td>
  339. <td align="center" valign="top">no</td>
  340. </tr>
  341. <tr>
  342. <td valign="top">includes</td>
  343. <td valign="top">Only check in files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
  344. <td align="center" valign="top">no</td>
  345. </tr>
  346. <tr>
  347. <td valign="top">excludes</td>
  348. <td valign="top">Do not check in files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
  349. <td align="center" valign="top">no</td>
  350. </tr>
  351. <tr>
  352. <td valign="top">recursive</td>
  353. <td valign="top">Indicates if subfolders should be searched for files to check in. Defaults to "false".</td>
  354. <td align="center" valign="top">no</td>
  355. </tr>
  356. <tr>
  357. <td valign="top">forced</td>
  358. <td valign="top">If true, checkins will occur regardless of the status
  359. that StarTeam is maintaining for the file. If false, checkins will use this status to decide which files to update. Defaults to "false".</td>
  360. <td align="center" valign="top">no</td>
  361. </tr>
  362. <td valign="top">unlocked</td>
  363. <td valign="top">If true, file will be unlocked so that other users may
  364. change it. If false (default) lock status will not change.
  365. <td align="center" valign="top">no</td>
  366. </tr>
  367. <tr>
  368. <td valign="top">preloadfileinformation</td>
  369. <td valign="top">The StarTeam server has the ability to preload file metadata for an
  370. entire tree prior to beginning action on that tree. Doing so can in some instances
  371. lead to substantially faster actions, particularly over large trees. Setting this
  372. to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>
  373. <td align="center" valign="top">no</td>
  374. </tr>
  375. </table>
  376. <h3>Examples</h3>
  377. <pre>
  378. &lt;stcheckin servername="STARTEAM"
  379. serverport="49201"
  380. projectname="AProject"
  381. viewname="AView"
  382. username="auser"
  383. password="secret"
  384. rootlocalfolder="C:\dev\buildtest\co"
  385. forced="true"
  386. /&gt;
  387. </pre>
  388. The minimum necessary to check files into a StarTeam server. This will
  389. check all files on the local tree rooted at <code>C:\dev\buildtest\co</code>
  390. into the <i>AView</i> view of the <i>AProject</i> project in the repository.
  391. For files and folders in the local tree but not in starteam, nothing will be done. Since the <i>forced</i> attribute is set, the files which are checked in will be checked in without regard to what the StarTeam repository considers their status to be. This is a reasonable choice of attributes since StarTeam's status for a file is calculated based on the local file in the StarTeam default directory, not on the directory we are actually working with.
  392. <pre>
  393. &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
  394. username="auser"
  395. password="secret"
  396. rootlocalfolder="C:\dev\buildtest\co"
  397. forced="true"
  398. /&gt;
  399. </pre>
  400. And this is a simpler way of giving the same commands as the command above using the URL shortcut.
  401. <br></br>
  402. <pre>
  403. &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
  404. username="auser"
  405. password="secret"
  406. rootlocalfolder="C:\dev\buildtest\co"
  407. rootstarteamfolder="\Dev"
  408. excludes="*.bak *.old"
  409. forced="true"
  410. /&gt;
  411. </pre>
  412. This will check all files in to the <i>Dev</i> folder and below that do not
  413. end in <i>.bak</i> or <i>.old</i> from the tree rooted at"C:\dev\buildtest\co" .
  414. <pre>
  415. &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
  416. username="auser"
  417. password="secret"
  418. rootlocalfolder="C:\dev\buildtest\co"
  419. includes="*.htm,*.html"
  420. excludes="index.*"
  421. forced="true"
  422. /&gt;
  423. </pre>
  424. This is an example of overlapping <i>includes</i> and <i>excludes</i> attributes. Because
  425. <i>excludes</i> takes precedence over <i>includes</i>, files named <code>index.html</code> will
  426. not be checked in by this command.
  427. <pre>
  428. &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
  429. username="auser"
  430. password="secret"
  431. rootlocalfolder="C:\dev\buildtest\co"
  432. rootstarteamfolder="src/java"
  433. includes="*.htm,*.html"
  434. excludes="index.*"
  435. forced="true"
  436. recursive="false"
  437. /&gt;
  438. </pre>
  439. This example is like the previous one, but will only check in files from
  440. C:\dev\buildtest\co, because of the turning off of the recursive attribute.
  441. <pre>
  442. &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
  443. username="auser"
  444. password="secret"
  445. rootlocalfolder="C:\dev\buildtest\co"
  446. rootstarteamfolder="src/java"
  447. includes="version.txt"
  448. forced="true"
  449. recursive="false"
  450. /&gt;
  451. </pre>
  452. This example is like the previous one, but will only check only in one file, C:\dev\buildtest\co\version.txt to the StarTeam folder src/java.
  453. <pre>
  454. &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
  455. username="auser"
  456. password="secret"
  457. rootlocalfolder="C:\dev\buildtest\co"
  458. rootstarteamfolder="src/java"
  459. includes="version.java"
  460. forced="true"
  461. recursive="false"
  462. addUncontrolled="true"
  463. comment="Fix Bug #667"
  464. /&gt;
  465. </pre>
  466. This example is like the previous one, but will only check only in one file, C:\dev\buildtest\co\version.java to the StarTeam folder src/java. Because the <i>addUncontrolled</i> attribute has been set, if StarTeam does not already control this file in this location, it will be added to the repository. Also, it will write a comment to the repository for this version of the file.
  467. <pre>
  468. &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
  469. username="auser"
  470. password="secret"
  471. rootstarteamfolder="src/java"
  472. rootlocalfolder="C:\dev\buildtest\co"
  473. forced="true"
  474. /&gt;
  475. </pre>
  476. <br></br>
  477. <pre>
  478. &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
  479. username="auser"
  480. password="secret"
  481. rootstarteamfolder="src/java"
  482. /&gt;
  483. </pre>
  484. <br></br>
  485. <pre>
  486. &lt;stcheckin URL="STARTEAM:49201/Aproject/AView"
  487. username="auser"
  488. password="secret"
  489. rootstarteamfolder="src/java"
  490. rootlocalfolder="C:\dev\buildtest\co\src\java"
  491. forced="true"
  492. /&gt;
  493. </pre>
  494. In the preceding three examples, assuming that the AProject project has a default folder of C:\work\buildtest\co\AProject,
  495. the first example will check in files from a tree rooted at C:\dev\buildtest\co,
  496. the second from a tree rooted at C:\work\buildtest\co\AProject\src\java,
  497. and the third from a tree rooted at C:\dev\buildtest\co\src\java all to a tree rooted at src/java
  498. <hr></hr>
  499. <a name="stlabel">
  500. <h2>STLabel</h2></a>
  501. <h3>Description</h3>
  502. Creates a view label in StarTeam at the specified view. The label will be classified by StarTeam as a "build label". This task will fail if there already exists in <i>viewname</i> a label with the same name as the <i>label</i> parameter.
  503. <h3>Parameters</h3>
  504. See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
  505. <table border="1" cellpadding="2" cellspacing="0">
  506. <tr>
  507. <td valign="top"><b>Attribute</b></td>
  508. <td valign="top"><b>Description</b></td>
  509. <td align="center" valign="top"><b>Required</b></td>
  510. </tr>
  511. <tr>
  512. <td valign="top">label</td>
  513. <td valign="top">The name to be given to the label</td>
  514. <td align="center" valign="top">yes</td>
  515. </tr>
  516. <tr>
  517. <td valign="top">description</td>
  518. <td valign="top">A description of the label to be stored in the StarTeam project.</td>
  519. <td align="center" valign="top">yes</td>
  520. </tr>
  521. <tr>
  522. <td valign="top">revisionlabel</td>
  523. <td valign="top">Yes means that the label attribute is to be saved as a &quot;revision label&quot;. No (default) means that it will be saved as a &quot;view label&quot;</td>
  524. <td align="center" valign="top">no</td>
  525. </tr>
  526. <tr>
  527. <td valign="top">buildlabel</td>
  528. <td valign="top">Yes means that the label attribute is to be saved as a &quot;build label&quot;.
  529. This means that Change Requests which have an &quot;AddressedIn&quot; field value of &quot;next build&quot;
  530. will have this label assigned to that field when the label is created.
  531. No (default) means that no CRs will have this label assigned to them. This will have no effect if <b>revisionlabel</b> is also true. </td>
  532. <td align="center" valign="top">no</td>
  533. </tr>
  534. <tr>
  535. <td valign="top">lastbuild</td>
  536. <td valign="top">The timestamp of the build that will be stored with the label. Must be formatted <code>yyyyMMddHHmmss</code></td>
  537. <td align="center" valign="top">no</td>
  538. </tr>
  539. </table>
  540. <h3>Examples</h3>
  541. This example shows the use of this tag. It will create a View label that is a build label named <i>Version 6.2</i> with
  542. <i>&quot;Thorough description&quot;</i> as its description.
  543. <pre>
  544. &lt;tstamp&gt;
  545. &lt;format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/&gt;
  546. &lt;/tstamp&gt;
  547. &lt;stlabel URL="STARTEAM:49201/Aproject/AView"
  548. username="auser"
  549. password="secret"
  550. label="Version 6.2"
  551. lastbuild="${nowstamp}"
  552. description="Thorough description"
  553. /&gt;
  554. </pre>
  555. This example creates a non-build View label named <i>Version 6.3</i> with
  556. <i>&quot;Thorough description&quot;</i> as its description.
  557. <pre>
  558. &lt;tstamp&gt;
  559. &lt;format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/&gt;
  560. &lt;/tstamp&gt;
  561. &lt;stlabel URL="STARTEAM:49201/Aproject/AView"
  562. username="auser"
  563. password="secret"
  564. label="Version 6.3"
  565. lastbuild="${nowstamp}"
  566. description="Thorough description"
  567. buildlabel="false"
  568. /&gt;
  569. </pre>
  570. This example will create a Revision label that is a build label named <i>Version 6.2.00.001</i> with
  571. <i>&quot;revision label&quot;</i> as its description.
  572. <pre>
  573. &lt;tstamp&gt;
  574. &lt;format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/&gt;
  575. &lt;/tstamp&gt;
  576. &lt;stlabel URL="STARTEAM:49201/Aproject/AView"
  577. username="auser"
  578. password="secret"
  579. label="Version 6.2.00.001"
  580. description="revision label"
  581. revisionlabel="true"
  582. /&gt;
  583. </pre>
  584. <hr></hr>
  585. <a name="stlist">
  586. <h2>STList</h2></a>
  587. <h3>Description</h3>
  588. Produces a listing of the contents of the StarTeam repository at the specified view and StarTeamFolder. The listing will contain the name of the user, if any, who has the file locked, the size of the file, its lastModifiedDate in the repository, the name of the file, and the status of the local file in the default local directory relative to the repository.
  589. <h3>Parameters</h3>
  590. See also <A href="#common-params">the required common StarTeam parameters</A>.<br></br>
  591. <table border="1" cellpadding="2" cellspacing="0">
  592. <tr>
  593. <td valign="top"><b>Attribute</b></td>
  594. <td valign="top"><b>Description</b></td>
  595. <td align="center" valign="top"><b>Required</b></td>
  596. </tr>
  597. <tr>
  598. <td valign="top">rootstarteamfolder</td>
  599. <td valign="top">The root of the subtree in the StarTeam repository to be listed. Defaults to the root folder of the view ('/'). <b><i>If supplied, this should always be an "absolute" path, that is, it should begin with a '/'.
  600. Relative paths have little meaning in this context and confuse StarTeam.</i></b></td>
  601. <td align="center" valign="top">no</td>
  602. </tr>
  603. <tr>
  604. <td valign="top">rootlocalfolder</td>
  605. <td valign="top">The local folder which will be the root of the tree to which files are compared. If this is not supplied, then the StarTeam "default folder" associated with <i>rootstarteamfolder</i> is used and a status field will appear in the listing. Otherwise, the status field will not appear.
  606. </td>
  607. <td align="center" valign="top">no</td>
  608. </tr>
  609. <tr>
  610. <td valign="top">includes</td>
  611. <td valign="top">Only list files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
  612. <td align="center" valign="top">no</td>
  613. </tr>
  614. <tr>
  615. <td valign="top">excludes</td>
  616. <td valign="top">Do not list files that match at least one of the patterns in this list. Patterns must be separated by <i>commas</i>. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
  617. <td align="center" valign="top">no</td>
  618. </tr>
  619. <tr>
  620. <td valign="top">label</td>
  621. <td valign="top">List files, dates, and statuses as of this label. The label must exist in starteam or an exception will be thrown. If not specified, the most recent version of each file will be listed.</td>
  622. <td align="center" valign="top">no</td>
  623. </tr>
  624. <tr>
  625. <td valign="top">asofdate</td>
  626. <td valign="top">List files, dates, and statuses as of this date.
  627. The date must be formatted in ISO8601 datetime
  628. (<code>yyyy-MM-dd'T'HH:mm:ss</code>), ISO8601
  629. date(<code>yyyy-MM-dd</code>) or a user-defined SimpleDateFormat
  630. defined in the <code>asofDateFormat</code> attribute. If the date
  631. is not parsable by the default or selected format, an exception
  632. will be thrown. <em>Since Ant 1.6.</em></td>
  633. <td align="center" valign="top">no</td>
  634. </tr>
  635. <tr>
  636. <td valign="top">asofdateformat</td>
  637. <td valign="top">java.util.SimpleDateFormat compatible string used
  638. to parse the <code>asofdate</code> attribute. <em>Since Ant
  639. 1.6.</em></td>
  640. <td align="center" valign="top">no</td>
  641. </tr>
  642. <tr>
  643. <td valign="top">recursive</td>
  644. <td valign="top">Indicates if subfolders should be searched for files to list. Defaults to "true".</td>
  645. <td align="center" valign="top">no</td>
  646. </tr>
  647. <tr>
  648. <td valign="top">listuncontrolled</td>
  649. <td valign="top">if true, any files or folders NOT in StarTeam will be included in the listing.
  650. If false, they won't. Defaults to "true".</td>
  651. <td align="center" valign="top">no</td>
  652. </tr>
  653. <tr>
  654. <td valign="top">preloadfileinformation</td>
  655. <td valign="top">The StarTeam server has the ability to preload file metadata for an
  656. entire tree prior to beginning action on that tree. Doing so can in some instances
  657. lead to substantially faster actions, particularly over large trees. Setting this
  658. to "yes" (default) engages this functionality, setting it to "no" turns it off.</td>
  659. <td align="center" valign="top">no</td>
  660. </tr>
  661. </table>
  662. <h3>Examples</h3>
  663. <pre>
  664. &lt;stlist url="WASHINGTON:49201/build"
  665. username="auser"
  666. password="secret"
  667. /&gt;
  668. </pre>
  669. The above command might produce the following listing:
  670. <pre>
  671. [stlist] Folder: Build (Default folder: C:/work/build)
  672. [stlist] Folder: dev (Default folder: C:/work/build/dev)
  673. [stlist] Out of date Sue Developer 1/1/02 7:25:47 PM CST 4368 build.xml
  674. [stlist] Missing George Hacker 1/1/02 7:25:49 PM CST 36 Test01.properties
  675. [stlist] Current 1/1/02 7:25:49 PM CST 4368 build2.xml
  676. [stlist] Folder: test (Default folder C:/work/build/dev/test)
  677. [stlist] Missing 1/1/02 7:25:50 PM CST 4368 build2.xml
  678. </pre>
  679. while adding a <i>rootlocalfolder</i> and an <i>excludes</i> param ...
  680. <pre>
  681. &lt;stlist url="WASHINGTON:49201/build"
  682. username="auser"
  683. password="secret"
  684. rootlocalfolder="srcdir2"
  685. excludes="*.properties"
  686. /&gt;
  687. </pre>
  688. might produce this listing. The status is missing because we are not going against the default folder.
  689. <pre>
  690. [stlist] overriding local folder to srcdir2
  691. [stlist] Folder: Build (Local folder: srcdir2)
  692. [stlist] Folder: dev (Local folder: srcdir2/dev)
  693. [stlist] Sue Developer 1/1/02 7:25:47 PM CST 4368 build.xml
  694. [stlist] 1/1/02 7:25:49 PM CST 4368 build2.xml
  695. [stlist] Folder: test (Local folder: srcdir2/dev/test)
  696. [stlist] 1/1/02 7:25:50 PM CST 4368 build2.xml
  697. </pre>
  698. <hr></hr>
  699. <a name="starteam">
  700. <h2>Starteam</h2></a>
  701. <h3><i>Deprecated</i></h3>
  702. <p><i>This task has been deprecated. Use the <a href="#stcheckout">STCheckout</a> task instead.</i></p>
  703. <h3>Description</h3>
  704. Checks out files from a StarTeam project.
  705. <p>
  706. The <i>includes</i> and <i>excludes</i> attributes function differently from
  707. other tasks in Ant. Multiple patterns must be separated by spaces, not
  708. commas. See the examples for more information.</p>
  709. <h3>Parameters</h3>
  710. <table border="1" cellpadding="2" cellspacing="0">
  711. <tr>
  712. <td valign="top"><b>Attribute</b></td>
  713. <td valign="top"><b>Description</b></td>
  714. <td align="center" valign="top"><b>Required</b></td>
  715. </tr>
  716. <tr>
  717. <td valign="top">username</td>
  718. <td valign="top">The username of the account used to log in to the StarTeam server.</td>
  719. <td align="center" valign="top">yes</td>
  720. </tr>
  721. <tr>
  722. <td valign="top">password</td>
  723. <td valign="top">The password of the account used to log in to the StarTeam server.</td>
  724. <td align="center" valign="top">yes</td>
  725. </tr>
  726. <tr>
  727. <td valign="top">servername</td>
  728. <td valign="top">The name of the StarTeam server.</td>
  729. <td align="center" valign="top">yes</td>
  730. </tr>
  731. <tr>
  732. <td valign="top">serverport</td>
  733. <td valign="top">The port number of the StarTeam server.</td>
  734. <td align="center" valign="top">yes</td>
  735. </tr>
  736. <tr>
  737. <td valign="top">projectname</td>
  738. <td valign="top">The name of the StarTeam project.</td>
  739. <td align="center" valign="top">yes</td>
  740. </tr>
  741. <tr>
  742. <td valign="top">viewname</td>
  743. <td valign="top">The name of the view in the StarTeam project.</td>
  744. <td align="center" valign="top">yes</td>
  745. </tr>
  746. <tr>
  747. <td valign="top">targetfolder</td>
  748. <td valign="top">The folder to which files are checked out. What this precisely means is determined by the <i>targetFolderAbsolute</i> param.</td>
  749. <td align="center" valign="top">yes</td>
  750. </tr>
  751. <tr>
  752. <td valign="top">targetFolderAbsolute</td>
  753. <td valign="top">Determines how <i>targetfolder</i> is interpreted, that is, whether the StarTeam "default folder" for the project is factored in (false) or whether <i>targetFolder</i> is a complete mapping to <i>foldername</i> (true).
  754. If "true", the target tree will be rooted at <i>targetfolder+"default folder"</i>. If false, the target tree will be rooted at <i>targetfolder</i>. Defaults to "false". </td>
  755. <td align="center" valign="top">no</td>
  756. </tr>
  757. <tr>
  758. <td valign="top">foldername</td>
  759. <td valign="top">The subfolder in the project from which to check out files.</td>
  760. <td align="center" valign="top">no</td>
  761. </tr>
  762. <tr>
  763. <td valign="top">force</td>
  764. <td valign="top">Overwrite existing folders if this is set to "true". Defaults to "false".</td>
  765. <td align="center" valign="top">no</td>
  766. </tr>
  767. <tr>
  768. <td valign="top">recursion</td>
  769. <td valign="top">Indicates if subfolders should be searched for files to check out. Defaults to "true".</td>
  770. <td align="center" valign="top">no</td>
  771. </tr>
  772. <tr>
  773. <td valign="top">verbose</td>
  774. <td valign="top">Provides progress information. Defaults to "false".</td>
  775. <td align="center" valign="top">no</td>
  776. </tr>
  777. <tr>
  778. <td valign="top">includes</td>
  779. <td valign="top">Only check out files that match at least one of the patterns in this list. Patterns must be separated by spaces. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
  780. <td align="center" valign="top">no</td>
  781. </tr>
  782. <tr>
  783. <td valign="top">excludes</td>
  784. <td valign="top">Do not check out files that match at least one of the patterns in this list. Patterns must be separated by spaces. Patterns in <i>excludes</i> take precedence over patterns in <i>includes</i>.</td>
  785. <td align="center" valign="top">no</td>
  786. </tr>
  787. </table>
  788. <h3>Examples</h3>
  789. <pre>
  790. &lt;starteam servername="STARTEAM"
  791. serverport="49201"
  792. projectname="AProject"
  793. viewname="AView"
  794. username="auser"
  795. password="secret"
  796. targetfolder="C:\dev\buildtest\co"
  797. /&gt;
  798. </pre>
  799. The minimum necessary to check out files out from a StarTeam server. This will
  800. check out all files in the <i>AView</i> view of the <i>AProject</i> project to
  801. <code>C:\dev\buildtest\co</code>.
  802. <pre>
  803. &lt;starteam servername="STARTEAM"
  804. serverport="49201"
  805. projectname="AProject"
  806. viewname="AView"
  807. username="auser"
  808. password="secret"
  809. targetfolder="C:\dev\buildtest\co"
  810. foldername="\Dev"
  811. excludes="*.bak *.old"
  812. force="true"
  813. /&gt;
  814. </pre>
  815. This will checkout all files from the <i>Dev</i> folder and below that do not
  816. end in <i>.bak</i> or <i>.old</i>. The force flag will cause any existing files to be
  817. overwritten by the version in StarTeam.
  818. <pre>
  819. &lt;starteam servername="STARTEAM"
  820. serverport="49201"
  821. projectname="AProject"
  822. viewname="AView"
  823. username="auser"
  824. password="secret"
  825. targetfolder="C:\dev\buildtest\co"
  826. includes="*.htm *.html"
  827. excludes="index.*"
  828. /&gt;
  829. </pre>
  830. This is an example of overlapping <i>includes</i> and <i>excludes</i> attributes. Because
  831. <i>excludes</i> takes precedence over <i>includes</i>, files named <code>index.html</code> will
  832. not be checked out by this command.
  833. <pre>
  834. &lt;starteam servername="STARTEAM"
  835. serverport="49201"
  836. projectname="AProject"
  837. foldername="src/java"
  838. viewname="AView"
  839. username="auser"
  840. password="secret"
  841. targetfolder="C:\dev\buildtest\co"
  842. targetfolderabsolute="true"
  843. /&gt;
  844. </pre>
  845. <br></br>
  846. <pre>
  847. &lt;starteam servername="STARTEAM"
  848. serverport="49201"
  849. projectname="AProject"
  850. foldername="src/java"
  851. viewname="AView"
  852. username="auser"
  853. password="secret"
  854. targetfolder="C:\dev\buildtest\co"
  855. targetfolderabsolute ="false"
  856. /&gt;
  857. </pre>
  858. <br></br>
  859. <pre>
  860. &lt;starteam servername="STARTEAM"
  861. serverport="49201"
  862. projectname="AProject"
  863. foldername="src/java"
  864. viewname="AView"
  865. username="auser"
  866. password="secret"
  867. targetfolder="C:\dev\buildtest\co\src\java"
  868. targetfolderabsolute="true"
  869. /&gt;
  870. </pre>
  871. In the preceding three examples, assuming that the AProject project has a default folder of
  872. "AProject", the first example will check the files located in starteam under src/java out to a tree rooted at C:\dev\buildtest\co,
  873. the second to a tree rooted at C:\dev\buildtest\co\AProject\src\java and the third to a tree rooted at C:\dev\buildtest\co\src\java.
  874. <hr>
  875. <p align="center">
  876. Copyright &copy; 2001-2004 The Apache Software Foundation. All rights Reserved.
  877. </p>
  878. </body>
  879. </html>