next up previous contents index
Next: STCheckin Up: Starteam Tasks Previous: Common Parameters for All   Contents   Index

STCheckout

Description

Checks out files from a StarTeam project.

The includes and excludes attributes function differently from other tasks in Ant. Inclusion/exclusion by folder is NOT supported.

Parameters

See also the required common StarTeam parameters.

Attribute Description Required
rootstarteamfolder The root of the subtree in the StarTeam repository from which to check out files. Defaults to the root folder of the view ('/'). no
rootlocalfolder 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 rootstarteamfolder is used. no
createworkingdirs creates local folders even when the corresponding StarTeam folder is empty. Defaults to "true". no
deleteuncontrolled if true, any files NOT in StarTeam will be deleted. Defaults to "true". no
includes Only check out files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. no
excludes Do not check out files that match at least one of the patterns in this list. Patterns must be separated by commas. Patterns in excludes take precedence over patterns in includes. no
label Check out files 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 checked out. no
recursive Indicates if subfolders should be searched for files to check out. Defaults to "true". no
forced If true, checkouts 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 checkout will be based on statuses which do not relate to the target folder. Defaults to "false". no
locked
unlocked
If true, file will be locked against changes by other users. If false (default) has no effect.
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.
Either or neither, but not both, may be true.

Examples

  <stcheckout servername="STARTEAM" 
              serverport="49201"
              projectname="AProject" 
              viewname="AView"
              username="auser"
              password="secret"
              rootlocalfolder="C:\dev\buildtest\co"
              force="true"
  />
The minimum necessary to check out files out from a StarTeam server. This will check out all files in the AView view of the AProject project to C: ${\backslash}{\backslash}$dev
buildtest
co. Empty folders in StarTeam will have local folders created for them and any non-StarTeam files found in the tree will be deleted.
  <stcheckout URL="STARTEAM:49201/Aproject/AView" 
              username="auser"
              password="secret"
              rootlocalfolder="C:\dev\buildtest\co"
              forced="true"
  />
And this is a simpler way of accomplishing the same thing as the previous example, using the URL attribute.
  <stcheckout URL="STARTEAM:49201/Aproject/AView" 
              username="auser"
              password="secret"
              rootlocalfolder="C:\dev\buildtest\co"
              rootstarteamfolder="\Dev"
              excludes="*.bak *.old"
              label="v2.6.001"
              forced="true"
  />
This will check out all files from the Dev folder and below that do not end in .bak or .old with the label v2.6.001.
  <stcheckout URL="STARTEAM:49201/Aproject/AView"
              username="auser"
              password="secret"
              rootlocalfolder="C:\dev\buildtest\co"
              includes="*.htm,*.html"
              excludes="index.*"
              forced="true"
  />
This is an example of overlapping includes and excludes attributes. Because excludes takes precedence over includes, files named index.html will not be checked out by this command.
  <stcheckout URL="STARTEAM:49201/Aproject/AView"
              username="auser"
              password="secret"
              rootlocalfolder="C:\dev\buildtest\co"
              includes="*.htm,*.html"
              excludes="index.*"
              forced="true"
              recursive="false"
  />
This example is like the previous one, but will only check out files in C: ${\backslash}{\backslash}$dev ${\backslash}{\backslash}$buildtest ${\backslash}{\backslash}$co, because of the turning off of the recursive attribute.
  <stcheckout URL="STARTEAM:49201/Aproject/AView"
              username="auser"
              password="secret"
              rootstarteamfolder="src/java"
              rootlocalfolder="C:\dev\buildtest\co"
              forced="true"
  />



  <stcheckout URL="STARTEAM:49201/Aproject/AView"
              username="auser"
              password="secret"
              rootstarteamfolder="src/java"
  />



 <stcheckout URL="STARTEAM:49201/Aproject/AView"
             username="auser"
             password="secret"
             rootstarteamfolder="src/java"
             rootlocalfolder="C:\dev\buildtest\co\src\java"
             forced="true"
  />
In the preceding three examples, assuming that the AProject project has a default folder of "C: ${\backslash}{\backslash}$work ${\backslash}{\backslash}$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: ${\backslash}{\backslash}$dev ${\backslash}{\backslash}$buildtest ${\backslash}{\backslash}$co, the second to a tree rooted at C: ${\backslash}{\backslash}$work ${\backslash}{\backslash}$AProject ${\backslash}{\backslash}$src ${\backslash}{\backslash}$java (since no rootlocalfolder is specified) and the third to a tree rooted at C: ${\backslash}{\backslash}$dev ${\backslash}{\backslash}$buildtest ${\backslash}{\backslash}$co ${\backslash}{\backslash}$src ${\backslash}{\backslash}$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.


next up previous contents index
Next: STCheckin Up: Starteam Tasks Previous: Common Parameters for All   Contents   Index
Andrew Marlow 2003-07-08