StarTeam Tasks User Manual

by

2002/03/22

Contents


Introduction

This program makes use of functions from the StarTeam Java API. As a result this task is only available to licensed users of StarTeam. You must have starteam-sdk.jar in your classpath to run this task. For more information about the StarTeam API and how to license it, see the StarBase web site.

The Tasks

starteamcheckout Checks out files from a StarTeam project.
starteamcheckin Checks in files to a StarTeam project.
starteamlabel Labels a StarTeam View or individual StarTeam Items.

Task Descriptions

starteamcheckout

Description

Checks out files from a StarTeam project to the local file system.

Note, the older task name 'starteam' is now deprecated, however it will continue to perform the check out task for the time being.

The includes and excludes attributes function differently from other tasks in Ant. Multiple patters must be seperated by spaces, not commas. See the examples for more information.

Parameters

Attribute Description Required
servername The name of the StarTeam server. yes
serverport The port number of the StarTeam server. yes
projectname The name of the StarTeam project. yes
viewname The name of the view in the StarTeam project. yes
username The username of the account used to log in to the StarTeam server. yes
password The password of the account used to log in to the StarTeam server. yes
targetfolder The folder to which files are checked out. yes
foldername The subfolder in the project from which to check out files. no
force Overwrite existing folders if this is set to "true". Defaults to "false". no
recursion Indicates if subfolders should be searched for files to check out. Defaults to "true". no
verbose Provides progress information. Defaults to "false". no
includes Only check out files that match at least one of the patterns in this list. Patterns must be seperated by spaces. 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 seperated by spaces. Patterns in excludes take precedence over patterns in includes. no

Examples

  <starteamcheckout servername="STARTEAM"
            serverport="49201"
            projectname="AProject"
            viewname="AView"
            username="auser"
            password="secret"
            targetfolder="C:\dev\buildtest\co"
  />
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:\dev\buildtest\co. 
  <starteamcheckout servername="STARTEAM"
            serverport="49201"
            projectname="AProject"
            viewname="AView"
            username="auser"
            password="secret"
            targetfolder="C:\dev\buildtest\co"
            foldername="\Dev"
            excludes="*.bak *.old"
            force="true"
  />
This will check out all files from the Dev folder and below that do not end in .bak or .old. The force flag will cause any existing files to be overwritten by the version in StarTeam. 
  <starteamcheckout servername="STARTEAM"
            serverport="49201"
            projectname="AProject"
            viewname="AView"
            username="auser"
            password="secret"
            targetfolder="C:\dev\buildtest\co"
            includes="*.htm *.html"
            excludes="index.*"
  />
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.

starteamcheckin

Description

Checks in files to a StarTeam project from the local file system.

The includes and excludes attributes function differently from other tasks in Ant. Multiple patters must be seperated by spaces, not commas. See the examples for more information.

Parameters

Attribute Description Required
servername The name of the StarTeam server. yes
serverport The port number of the StarTeam server. yes
projectname The name of the StarTeam project. yes
viewname The name of the view in the StarTeam project. yes
username The username of the account used to log in to the StarTeam server. yes
password The password of the account used to log in to the StarTeam server. yes
sourcefolder The folder from which files are checked in. yes
reason The comment to add to this newly checked-in revision. Defaults to an empty string. no
foldername The subfolder in the project in which to check in files. no
force Checks in files, even if the status is something other than 'modified', if this is set to "true". Defaults to "false". no
recursion Indicates if subfolders should be searched for files to check in. Defaults to "true". no
verbose Provides progress information. Defaults to "false". no
includes Only check in files that match at least one of the patterns in this list. Patterns must be seperated by spaces. Patterns in excludes take precedence over patterns in includes. no
excludes Do not check in files that match at least one of the patterns in this list. Patterns must be seperated by spaces. Patterns in excludes take precedence over patterns in includes. no

Examples

  <starteamcheckin servername="STARTEAM"
            serverport="49201"
            projectname="AProject"
            viewname="AView"
            username="auser"
            password="secret"
            sourcefolder="C:\dev\buildtest\co"
  />
The minimum necessary to check in files into a StarTeam server. This will check in all files in the AView view of the AProject project from C:\dev\buildtest\co. 
  <starteamcheckin servername="STARTEAM"
            serverport="49201"
            projectname="AProject"
            viewname="AView"
            username="auser"
            password="secret"
            sourcefolder="C:\dev\buildtest\co"
            foldername="\Dev"
            excludes="*.bak *.old"
            force="true"
  />
This will check in all files to the Dev folder and below that do not end in .bak or .old. The force flag will cause all files to be checked in regardless of whether they have been modified or not. 
  <starteamcheckin servername="STARTEAM"
            serverport="49201"
            projectname="AProject"
            viewname="AView"
            username="auser"
            password="secret"
            sourcefolder="C:\dev\buildtest\co"
            includes="*.htm *.html"
            excludes="index.*"
            reason="Fixed table formatting."
  />
This is an example of overlapping includes and excludes attributes. Because excludes takes precedence over includes, files named index.html will not be checked in by this command. Also, the given comment will be supplied to the StarTeam server.

starteamlabel

Description

Labels a View or individual items (files, folders, etc) on a StarTeam server.

The includes and excludes attributes function differently from other tasks in Ant. Multiple patters must be seperated by spaces, not commas. See the examples for more information.

Parameters

Attribute Description Required
servername The name of the StarTeam server. yes
serverport The port number of the StarTeam server. yes
projectname The name of the StarTeam project. yes
viewname The name of the view in the StarTeam project. yes
username The username of the account used to log in to the StarTeam server. yes
password The password of the account used to log in to the StarTeam server. yes
name The name of the label. Must be unique. yes
description The description of the label. Defaults to an empty string. no
viewlabel If true, the label is applied only to the View (View-Label if true, Revision-Label if false). Defaults to "false". no
foldername The subfolder in the project in which to check in files. Ignored when viewlabel is true no
buildlabel If true, the label is marked as a build label. Ignored when viewlabel is false. Defaults to "false". no
force Currently unused. Defaults to "false". no
recursion Indicates if subfolders should be searched for items to label. Ignored when viewlabel is true. Defaults to "true". no
verbose Provides progress information. Defaults to "false". no
includes Only check in files that match at least one of the patterns in this list. Patterns must be seperated by spaces. Patterns in excludes take precedence over patterns in includes. Ignored when viewlabel is true no
excludes Do not check in files that match at least one of the patterns in this list. Patterns must be seperated by spaces. Patterns in excludes take precedence over patterns in includes. Ignored when viewlabel is true no

Examples

  <starteamlabel servername="STARTEAM"
            serverport="49201"
            projectname="AProject"
            viewname="AView"
            username="auser"
            password="secret"
            name="Label123"
  />
The minimum necessary to label item in a StarTeam server. This will label all files in the AView view of the AProject project. 
  <starteamlabel servername="STARTEAM"
            serverport="49201"
            projectname="AProject"
            viewname="AView"
            username="auser"
            password="secret"
            name="Label123"
            description="This is my latest revision"
            excludes="*.bak *.old"
  />
This will label all items in the view aView and below that do not end in .bak or .old. The description will also be set. 
  <starteamlabel servername="STARTEAM"
            serverport="49201"
            projectname="AProject"
            viewname="AView"
            username="auser"
            password="secret"
            name="3.2.1.0"
            description="Final Build for version 3.2.1.0"
            viewlabel="true"
            buildlabel="true"
  />
This will label only the view aView and will set it to be a build label. All items under this view will also have the label, however, deleting the label from the view will also delete the label from all the child items.

Copyright © 2000,2001 Apache Software Foundation. All rights Reserved.