sbailliez 02/01/14 14:25:56
Modified: docs/manual/OptionalTasks starteam.html
Log:
Add additional StarTeam tasks
PR: 5650
Submitted by: [EMAIL PROTECTED] (Steve Cohen)
Revision Changes Path
1.9 +357 -72 jakarta-ant/docs/manual/OptionalTasks/starteam.html
Index: starteam.html
===================================================================
RCS file: /home/cvs/jakarta-ant/docs/manual/OptionalTasks/starteam.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -r1.8 -r1.9
--- starteam.html 10 Jan 2002 08:48:31 -0000 1.8
+++ starteam.html 14 Jan 2002 22:25:56 -0000 1.9
@@ -6,9 +6,10 @@
<body>
<h1>StarTeam Support</h1>
<ul>
-<!-- <li><a href="#stcheckin">STCheckin</a></li>-->
- <li><a href="#stcheckout">STCheckout</a></li>
+ <li><a href="#stcheckout">STCheckout</a></li>
+ <li><a href="#stcheckin">STCheckin</a></li>
<li><a href="#stlabel">STLabel</a></li>
+ <li><a href="#stlist">STList</a></li>
<li><a href="#starteam"><i>StarTeam (deprecated) </i></a></li>
</ul>
@@ -21,19 +22,12 @@
<hr></hr>
-<a name="stcheckout">
-<h2>STCheckout</h2></a>
-
-<h3>Description</h3>
-
-Checks out files from a StarTeam project.
-
+<a name="common-params">
+<h2>Common Parameters for All Starteam Tasks</h2></a>
<p>
-The <i>includes</i> and <i>excludes</i> attributes function differently from
-other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
+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.
</p>
-<h3>Parameters</h3>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
<td valign="top">username</td>
@@ -50,28 +44,47 @@
<td valign="top">URL</td>
<td valign="top">A string of the form
<code>servername:portnum/project/view</code>
which enables user to set all of these elements in one string. </td>
- <td align="center" valign="top">yes*</td>
- </tr> <tr>
+ <td align="center" valign="center"> Either this ...</td>
+ </tr>
+ <tr>
<td valign="top">servername</td>
<td valign="top">The name of the StarTeam server.</td>
- <td align="center" valign="top">yes*</td>
- </tr>
+ <td align="center" valign="center" rowspan = "4">... or <b>all four</b>
of these must be defined.</td>
+ </tr>
<tr>
<td valign="top">serverport</td>
<td valign="top">The port number of the StarTeam server.</td>
- <td align="center" valign="top">yes*</td>
</tr>
<tr>
<td valign="top">projectname</td>
- <td valign="top">The name of the StarTeam project.</td>
- <td align="center" valign="top">yes*</td>
+ <td valign="top">The name of the StarTeam project on which to
operate.</td>
</tr>
<tr>
<td valign="top">viewname</td>
- <td valign="top">The name of the view in the StarTeam project.</td>
- <td align="center" valign="top">yes*</td>
+ <td valign="top">The name of the view in the StarTeam project on which
to operate.</td>
</tr>
+
+</table>
+
+<hr></hr>
+
+<a name="stcheckout">
+<h2>STCheckout</h2></a>
+
+<h3>Description</h3>
+
+Checks out files from a StarTeam project.
+
+<p>
+The <i>includes</i> and <i>excludes</i> attributes function differently from
+other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
+</p>
+
+<h3>Parameters</h3>
+See also <A href="#common-params">the required common StarTeam
parameters</A>.<br></br>
+<table border="1" cellpadding="2" cellspacing="0">
+
<tr>
<td valign="top">rootstarteamfolder</td>
<td valign="top">The root of the subtree in the StarTeam repository from
which to
@@ -80,9 +93,8 @@
</tr>
<tr>
<td valign="top">rootlocalfolder</td>
- <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.
- Setting this may be thought of as setting a different mode of operation,
since when set, it makes no sense to check StarTeam's status flags for each
file, and they are not checked.
- When not set, we use the default folder and so we do check the status
flags.</td>
+ <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>
<td align="center" valign="top">no</td>
</tr>
@@ -123,11 +135,21 @@
this should be set "true" as otherwise the checkout will be based on
statuses
which do not relate to the target folder. Defaults to "false".</td>
<td align="center" valign="top">no</td>
+ </tr>
+ <tr>
+ <td valign="top">locked</td>
+ <td valign="top">If true, file will be locked against changes by other
+users. If false (default) has no effect.
+ <td align="center" valign="center" rowspan="2">Either or neither, but
not both, may be true.</td>
+ </tr>
+ <tr>
+ <td valign="top">unlocked</td>
+ <td valign="top">If true, file will be unlocked so that other users may
+change it. This is a way to reverse changes that have not yet been checked
in.
+If false (default) has no effect.
</tr>
</table>
-* Either the URL attribute or <b>all four</b> of the servername, serverport,
projectname and viewname attributes must be defined. <br/>
-
<h3>Examples</h3>
<pre>
@@ -147,15 +169,15 @@
<code>C:\dev\buildtest\co</code>. Empty folders in StarTeam will have local
folders
created for them and any non-StarTeam files found in the tree will be
deleted.
-Or more simply:
<pre>
<stcheckout URL="STARTEAM:49201/Aproject/AView"
username="auser"
password="secret"
rootlocalfolder="C:\dev\buildtest\co"
- force="true"
+ forced="true"
/>
</pre>
+And this is a simpler way of accomplishing the same thing as the previous
example, using the URL attribute.
<br></br>
<pre>
<stcheckout URL="STARTEAM:49201/Aproject/AView"
@@ -165,11 +187,11 @@
rootstarteamfolder="\Dev"
excludes="*.bak *.old"
label="v2.6.001"
- force="true"
+ forced="true"
/>
</pre>
-This will checkout all files from the <i>Dev</i> folder and below that do not
+This will check out all files from the <i>Dev</i> folder and below that do
not
end in <i>.bak</i> or <i>.old</i> with the label <i>v2.6.001</i>.
<pre>
@@ -179,7 +201,7 @@
rootlocalfolder="C:\dev\buildtest\co"
includes="*.htm,*.html"
excludes="index.*"
- force="true"
+ forced="true"
/>
</pre>
@@ -195,7 +217,7 @@
rootlocalfolder="C:\dev\buildtest\co"
includes="*.htm,*.html"
excludes="index.*"
- force="true"
+ forced="true"
recursive="false"
/>
</pre>
@@ -208,7 +230,7 @@
password="secret"
rootstarteamfolder="src/java"
rootlocalfolder="C:\dev\buildtest\co"
- force="true"
+ forced="true"
/>
</pre>
<br></br>
@@ -226,59 +248,231 @@
password="secret"
rootstarteamfolder="src/java"
rootlocalfolder="C:\dev\buildtest\co\src\java"
- force="true"
+ forced="true"
/>
</pre>
In the preceding three examples, assuming that the AProject project has a
default folder of
-"AProject", the first example will check the files located in starteam under
src/java out to a tree rooted at C:\dev\buildtest\co,
-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.
+"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,
+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.
+<hr></hr>
-<a name="stlabel">
-<h2>STLabel</h2></a>
+<a name="stcheckin">
+<h2>STCheckin</h2></a>
<h3>Description</h3>
-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 exexists in <i>viewname</i> a label with the same name as the
<i>label</i> parameter.
+Checks files into a StarTeam project. Optionally adds files and in the
local tree that are not managed by the repository to its control.
+
+<p>
+The <i>includes</i> and <i>excludes</i> attributes function differently from
+other tasks in Ant. Inclusion/exclusion by folder is NOT supported.
+</p>
<h3>Parameters</h3>
+See also <A href="#common-params">the required common StarTeam
parameters</A>.<br></br>
<table border="1" cellpadding="2" cellspacing="0">
<tr>
- <td valign="top">username</td>
- <td valign="top">The username of the account used to log in to the
StarTeam server.</td>
- <td align="center" valign="top">yes</td>
- </tr>
+ <td valign="top">rootstarteamfolder</td>
+ <td valign="top">The root of the subtree in the StarTeam repository into
which to
+ files will be checked. Defaults to the root folder of the view ('/').
</td>
+ <td align="center" valign="top">no</td>
+ </tr>
<tr>
- <td valign="top">password</td>
- <td valign="top">The password of the account used to log in to the
StarTeam server.</td>
- <td align="center" valign="top">yes</td>
+ <td valign="top">rootlocalfolder</td>
+ <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>
+ <td align="center" valign="top">no</td>
+ </tr>
+
+<!--
+ <tr>
+ <td valign="top">createworkingdirs</td>
+ <td valign="top">creates local folders even when the corresponding
StarTeam folder is empty. Defaults to "true".</td>
+ <td align="center" valign="top">no</td>
</tr>
-
+-->
<tr>
- <td valign="top">URL</td>
- <td valign="top">A string of the form
<code>"servername:portnum/project/view"</code>
-which enables user to set all of these elements in one string. </td>
- <td align="center" valign="top">yes*</td>
- </tr> <tr>
- <td valign="top">servername</td>
- <td valign="top">The name of the StarTeam server.</td>
- <td align="center" valign="top">yes*</td>
+ <td valign="top">adduncontrolled</td>
+ <td valign="top">if true, any files or folders NOT in StarTeam will be
+added to the repository. Defaults to "false".</td>
+ <td align="center" valign="top">no</td>
+ </tr>
+ <tr>
+ <td valign="top">includes</td>
+ <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>
+ <td align="center" valign="top">no</td>
</tr>
<tr>
- <td valign="top">serverport</td>
- <td valign="top">The port number of the StarTeam server.</td>
- <td align="center" valign="top">yes*</td>
+ <td valign="top">excludes</td>
+ <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>
+ <td align="center" valign="top">no</td>
</tr>
<tr>
- <td valign="top">projectname</td>
- <td valign="top">The name of the StarTeam project.</td>
- <td align="center" valign="top">yes*</td>
+ <td valign="top">recursive</td>
+ <td valign="top">Indicates if subfolders should be searched for files to
check in. Defaults to "true".</td>
+ <td align="center" valign="top">no</td>
</tr>
<tr>
- <td valign="top">viewname</td>
- <td valign="top">The name of the view in the StarTeam project.</td>
- <td align="center" valign="top">yes*</td>
+ <td valign="top">forced</td>
+ <td valign="top">If true, checkins will occur regardless of the status
+that StarTeam is maintaining for the file. If rootlocalfolder is set then
+this should be set "true" as otherwise the checkin will be based on statuses
+which do not relate to the target folder. Defaults to "false".</td>
+ <td align="center" valign="top">no</td>
</tr>
+ <td valign="top">unlocked</td>
+ <td valign="top">If true, file will be unlocked so that other users may
+change it. If false (default) lock status will not change.
+ <td align="center" valign="top">no</td>
+ </tr></table>
+
+<h3>Examples</h3>
+
+<pre>
+ <stcheckin servername="STARTEAM"
+ serverport="49201"
+ projectname="AProject"
+ viewname="AView"
+ username="auser"
+ password="secret"
+ rootlocalfolder="C:\dev\buildtest\co"
+ forced="true"
+ />
+</pre>
+
+The minimum necessary to check files into a StarTeam server. This will
+check all files on the local tree rooted at <code>C:\dev\buildtest\co</code>
+into the <i>AView</i> view of the <i>AProject</i> project in the repository.
+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.
+
+<pre>
+ <stcheckin URL="STARTEAM:49201/Aproject/AView"
+ username="auser"
+ password="secret"
+ rootlocalfolder="C:\dev\buildtest\co"
+ forced="true"
+ />
+</pre>
+And this is a simpler way of giving the same commands as the command above
using the URL shortcut.
+<br></br>
+<pre>
+ <stcheckin URL="STARTEAM:49201/Aproject/AView"
+ username="auser"
+ password="secret"
+ rootlocalfolder="C:\dev\buildtest\co"
+ rootstarteamfolder="\Dev"
+ excludes="*.bak *.old"
+ forced="true"
+ />
+</pre>
+
+This will check all files in to the <i>Dev</i> folder and below that do not
+end in <i>.bak</i> or <i>.old</i> from the tree rooted
at"C:\dev\buildtest\co" .
+
+<pre>
+ <stcheckin URL="STARTEAM:49201/Aproject/AView"
+ username="auser"
+ password="secret"
+ rootlocalfolder="C:\dev\buildtest\co"
+ includes="*.htm,*.html"
+ excludes="index.*"
+ forced="true"
+ />
+</pre>
+
+
+This is an example of overlapping <i>includes</i> and <i>excludes</i>
attributes. Because
+<i>excludes</i> takes precedence over <i>includes</i>, files named
<code>index.html</code> will
+not be checked in by this command.
+
+<pre>
+ <stcheckin URL="STARTEAM:49201/Aproject/AView"
+ username="auser"
+ password="secret"
+ rootlocalfolder="C:\dev\buildtest\co"
+ rootstarteamfolder="src/java"
+ includes="*.htm,*.html"
+ excludes="index.*"
+ forced="true"
+ recursive="false"
+ />
+</pre>
+This example is like the previous one, but will only check in files from
+C:\dev\buildtest\co, because of the turning off of the recursive attribute.
+
+<pre>
+ <stcheckin URL="STARTEAM:49201/Aproject/AView"
+ username="auser"
+ password="secret"
+ rootlocalfolder="C:\dev\buildtest\co"
+ rootstarteamfolder="src/java"
+ includes="version.txt"
+ forced="true"
+ recursive="false"
+ />
+</pre>
+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.
+
+<pre>
+ <stcheckin URL="STARTEAM:49201/Aproject/AView"
+ username="auser"
+ password="secret"
+ rootlocalfolder="C:\dev\buildtest\co"
+ rootstarteamfolder="src/java"
+ includes="version.txt"
+ forced="true"
+ recursive="false"
+ addUncontrolled="true"
+ />
+</pre>
+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. 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.
+
+<pre>
+ <stcheckin URL="STARTEAM:49201/Aproject/AView"
+ username="auser"
+ password="secret"
+ rootstarteamfolder="src/java"
+ rootlocalfolder="C:\dev\buildtest\co"
+ forced="true"
+ />
+</pre>
+<br></br>
+<pre>
+ <stcheckin URL="STARTEAM:49201/Aproject/AView"
+ username="auser"
+ password="secret"
+ rootstarteamfolder="src/java"
+ />
+</pre>
+<br></br>
+<pre>
+ <stcheckin URL="STARTEAM:49201/Aproject/AView"
+ username="auser"
+ password="secret"
+ rootstarteamfolder="src/java"
+ rootlocalfolder="C:\dev\buildtest\co\src\java"
+ forced="true"
+ />
+</pre>
+
+In the preceding three examples, assuming that the AProject project has a
default folder of C:\work\buildtest\co\AProject,
+the first example will check in files from a tree rooted at
C:\dev\buildtest\co,
+the second from a tree rooted at C:\work\buildtest\co\AProject\src\java,
+and the third from a tree rooted at C:\dev\buildtest\co\src\java all to a
tree rooted at src/java
+
+<hr></hr>
+
+<a name="stlabel">
+<h2>STLabel</h2></a>
+
+<h3>Description</h3>
+
+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 exexists in <i>viewname</i> a label with the same name as the
<i>label</i> parameter.
+
+<h3>Parameters</h3>
+See also <A href="#common-params">the required common StarTeam
parameters</A>.<br></br>
+<table border="1" cellpadding="2" cellspacing="0">
+
<tr>
<td valign="top">label</td>
<td valign="top">The name to be given to the label</td>
@@ -295,7 +489,6 @@
<td align="center" valign="top">no</td>
</tr>
</table>
-* Either the URL attribute or <b>all four</b> of the servername, serverport,
projectname and viewname attributes must be defined. <br/>
<h3>Examples</h3>
@@ -305,21 +498,113 @@
<tstamp>
<format property="nowstamp" pattern="yyyyMMddHHmmss" locale="en"/>
</tstamp>
- <starteamlabel URL="STARTEAM:49201/Aproject/AView"
- username="auser"
- password="secret"
- label="Version 6.2"
- lastbuild="${nowstamp}"
- description-"Thorough description"
+ <stlabel URL="STARTEAM:49201/Aproject/AView"
+ username="auser"
+ password="secret"
+ label="Version 6.2"
+ lastbuild="${nowstamp}"
+ description-"Thorough description"
/>
</pre>
<hr></hr>
+<a name="stlist">
+<h2>STList</h2></a>
+
+<h3>Description</h3>
+
+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, and the name of the file. Unless the
rootLocalFolder is specified, listing will also show the status of the local
file in the default local directory relative to the repository.
+
+<h3>Parameters</h3>
+See also <A href="#common-params">the required common StarTeam
parameters</A>.<br></br>
+<table border="1" cellpadding="2" cellspacing="0">
+
+ <tr>
+ <td valign="top">rootstarteamfolder</td>
+ <td valign="top">The root of the subtree in the StarTeam repository to
be listed. Defaults to the root folder of the view ('/'). </td>
+ <td align="center" valign="top">no</td>
+ </tr>
+ <tr>
+ <td valign="top">rootlocalfolder</td>
+ <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.
+ </td>
+ <td align="center" valign="top">no</td>
+ </tr>
+ <tr>
+ <td valign="top">includes</td>
+ <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>
+ <td align="center" valign="top">no</td>
+ </tr>
+ <tr>
+ <td valign="top">excludes</td>
+ <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>
+ <td align="center" valign="top">no</td>
+ </tr>
+ <tr>
+ <td valign="top">label</td>
+ <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>
+ <td align="center" valign="top">no</td>
+ </tr>
+ <tr>
+ <td valign="top">recursive</td>
+ <td valign="top">Indicates if subfolders should be searched for files to
list. Defaults to "true".</td>
+ <td align="center" valign="top">no</td>
+ </tr>
+</table>
+<h3>Examples</h3>
+
+<pre>
+
+ <stlist url="WASHINGTON:49201/build"
+ username="auser"
+ password="secret"
+ />
+</pre>
+
+The above command might produce the following listing:
+
+<pre>
+ [stlist] Folder: Build (Default folder: C:/work/build)
+ [stlist] Folder: dev (Default folder: C:/work/build/dev)
+ [stlist] Out of date Sue Developer 1/1/02 7:25:47 PM CST 4368
build.xml
+ [stlist] Missing George Hacker 1/1/02 7:25:49 PM CST 36
Test01.properties
+ [stlist] Current 1/1/02 7:25:49 PM CST 4368
build2.xml
+ [stlist] Folder: test (Default folder C:/work/build/dev/test)
+ [stlist] Missing 1/1/02 7:25:50 PM CST 4368
build2.xml
+</pre>
+
+while adding a <i>rootlocalfolder</i> and an <i>excludes</i> param ...
+
+<pre>
+
+ <stlist url="WASHINGTON:49201/build"
+ username="auser"
+ password="secret"
+ rootlocalfolder="srcdir2"
+ excludes="*.properties"
+ />
+</pre>
+
+might produce this listing. The status is missing because we are not going
against the default folder.
+
+<pre>
+ [stlist] overriding local folder to srcdir2
+ [stlist] Folder: Build (Local folder: srcdir2)
+ [stlist] Folder: dev (Local folder: srcdir2/dev)
+ [stlist] Sue Developer 1/1/02 7:25:47 PM CST 4368 build.xml
+ [stlist] 1/1/02 7:25:49 PM CST 4368 build2.xml
+ [stlist] Folder: test (Local folder: srcdir2/dev/test)
+ [stlist] 1/1/02 7:25:50 PM CST 4368 build2.xml
+
+
+</pre>
+
+<hr></hr>
<a name="starteam">
<h2>Starteam</h2></a>
<h3><i>Deprecated</i></h3>
-<p><i>This task has been deprecated. Use the <a
href=#stcheckout">STCheckout</a> task instead.</i></p>
+<p><i>This task has been deprecated. Use the <a
href="#stcheckout">STCheckout</a> task instead.</i></p>
<h3>Description</h3>
Checks out files from a StarTeam project.
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
