Microsoft Visual SourceSafe Tasks User Manual

Craig Cottingham
Andrew Everitt
Balazs Fejes 2
Glenn_Twiggs@bmc.com
Martin Poeschl (mpoeschl@marmot.at)
Phillip Wells
Jon Skeet (jon.skeet@peramon.com)
Nigel Magnay (nigel.magnay@parsec.co.uk)
Gary S. Weaver
Jesse Stockall

Introduction
The Tasks

Introduction

This antlib provides an interface to the Microsoft Visual SourceSafe SCM. The original tasks (org.apache.tools.ant.taskdefs.optional.vss) have been expanded upon in this antlib. Some fixes to issues in the original tasks have also been incorporated.

If you get a CreateProcesss IOError=2 when running these, it means that ss.exe was not found. Check to see if you can run it from the command line -you may need to alter your path, or set the ssdir property.

To use this antlib in your build file, you must first declare it eg:

<project name="myproject" basedir="." 
         default="test" xmlns:vss="antlib:org.apache.ant.vss">

The Tasks

vss:get	Retrieves a copy of the specified VSS file(s).
vss:label	Assigns a label to the specified version or current version of a file or project.
vss:history	Shows the history of a file or project in VSS.
vss:checkin	Updates VSS with changes made to a checked out file, and unlocks the VSS master copy.
vss:checkout	Copies a file from the current project to the current folder, for the purpose of editing.
vss:add	Adds a new file into the VSS Archive
vss:cp	Change the current project being used in VSS
vss:create	Creates a project in VSS.
vss:destroy	Permanently remove a file or project from VSS.
vss:move	Relocates a subproject from one parent project to another.
vss:cloak	Hides a project from recursive Get, Check Out, Check In, Undo Check Out, and Project Differences commands.
vss:decloak	Removes the cloaked attribute from a project.
vss:delete	Removes files and projects from VSS Explorer, and marks them as deleted; the items still exist, however, and can be recovered using the Recover command.
vss:recover	Recovers files and projects that have been deleted.
vss:locate	Searches through VSS projects for file or project names.
vss:status	Shows check out information on files.

Task Descriptions

vss:get

Description

Task to perform GET commands to Microsoft Visual SourceSafe.

If you specify two or more attributes from version, date and label only one will be used in the order version, date, label.

Parameters

Attribute	Values	Required
vsspath	SourceSafe path which specifies the project/file(s) you wish to perform the action on.	Yes
login	username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password.	No
localpath	Override the working directory and get to the specified path	No
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
serverPath	directory where `srcsafe.ini` resides.	No
writable	true or false; default false	No
recursive	true or false; default false. Note however that in the SourceSafe UI , there is a setting accessed via Tools/Options/GeneralTab called "Act on projects recursively". If this setting is checked, then the recursive attribute is effectively ignored, and the get will always be done recursively	No
version	a version number to get	No, only one of these allowed
date	a date stamp to get at
label	a label to get for
quiet	suppress output (off by default)	No
autoresponse	What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this.	No
writablefiles	Behavior when local files are writable. Valid options are: `replace`, `skip` and `fail`; Defaults to `fail` `skip` implies `failonerror=false`	No
failonerror	Stop the buildprocess if ss.exe exits with a returncode of 100. Defaults to true	No
filetimestamp	Set the behavior for timestamps of local files. Valid options are `current`, `modified`, or `updated`. Defaults to `current`.	No

Note that only one of version, date or label should be specified

Examples

<vss:get localPath="C:\mysrc\myproject"
        recursive="true"
        label="Release1"
        login="me,mypassword"
        vsspath="$/source/aProject"
        writable="true"/>

Does a get on the VSS-Project $/source/myproject using the username me and the password mypassword. It will recursively get the files which are labeled Release1 and write them to the local directory C:\mysrc\myproject. The local files will be writable.

vss:label

Description

Task to perform LABEL commands to Microsoft Visual SourceSafe.

Assigns a label to the specified version or current version of a file or project.

Parameters

Attribute	Values	Required
vsspath	SourceSafe path which specifies the project/file(s) you wish to perform the action on.	Yes
login	username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password.	No
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
serverPath	directory where `srcsafe.ini` resides.	No
label	A label to apply to the hierarchy	Yes
version	An existing file or project version to label. By default the current version is labeled.	No
comment	The comment to use for this label. Empty or '-' for no comment.	No
autoresponse	What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this.	No
failonerror	Stop the buildprocess if ss.exe exits with a returncode of 100. Defaults to true	No

Examples

<vss:label vsspath="$/source/aProject"
          login="me,mypassword"
          label="Release1"/>

Labels the current version of the VSS project $/source/aProject with the label Release1 using the username me and the password mypassword.

<vss:label vsspath="$/source/aProject/myfile.txt"
          version="4"
          label="1.03.004"/>

Labels version 4 of the VSS file $/source/aProject/myfile.txt with the label 1.03.004. If this version already has a label, the operation (and the build) will fail.

vss:history

Description

Task to perform HISTORY commands to Microsoft Visual SourceSafe.

Parameters

Attribute	Values	Required
vsspath	SourceSafe path which specifies the project/file(s) you wish to perform the action on.	Yes
login	username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password.	No
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
serverPath	directory where `srcsafe.ini` resides.	No
fromDate	Start date for comparison	See below
toDate	End date for comparison	See below
dateFormat	Format of dates in fromDate and toDate. Used when calculating dates with the numdays attribute. This string uses the formatting rules of SimpleDateFormat. Defaults to DateFormat.SHORT.	No
fromLabel	Start label for comparison	No
toLabel	Start label for comparison	No
numdays	The number of days for comparison.	See below
output	File to write the diff.	No
recursive	true or false	No
style	brief, codediff, default or nofile. The default is default.	No
user	Name the user whose changes we would like to see	No
failonerror	Stop the buildprocess if ss.exe exits with a returncode of 100. Defaults to true	No

Specifying the time-frame

There are different ways to specify what time-frame you wish to evaluate:

Changes between two dates: Specify both fromDate and toDate
Changes before a date: Specify toDate
Changes after a date: Specify fromDate
Changes X Days before a date: Specify toDate and (negative!) numDays
Changes X Days after a date: Specify fromDate and numDays

Examples

<vss:history vsspath="$/myProject" recursive="true"
            fromLabel="Release1"
            toLabel="Release2"/>

Shows all changes between "Release1" and "Release2".

<vss:history vsspath="$/myProject" recursive="true"
            fromDate="01.01.2001"
            toDate="31.03.2001"/>

Shows all changes between January 1st 2001 and March 31st 2001 (in Germany, date must be specified according to your locale).

<tstamp>
  <format property="to.tstamp" pattern="M-d-yy;h:mma"/>
</tstamp>

<vss:history vsspath="$/myProject" recursive="true"
            numDays="-14"
            dateFormat="M-d-yy;h:mma"
            toDate="${to.tstamp}"/>

Shows all changes in the 14 days before today.

vss:checkin

Description

Task to perform CHECKIN commands to Microsoft Visual SourceSafe.

Parameters

Attribute	Values	Required
vsspath	SourceSafe path which specifies the project/file(s) you wish to perform the action on.	Yes
login	username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password.	No
localpath	Override the working directory and get to the specified path	No
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
serverPath	directory where `srcsafe.ini` resides.	No
writable	true or false	No
recursive	true or false	No
comment	Comment to use for the files that where checked in.	No
autoresponse	'Y', 'N' or empty. Specify how to reply to questions from VSS.	No
failonerror	Stop the buildprocess if ss.exe exits with a returncode of 100. Defaults to true	No

Examples

<vss:checkin vsspath="$/test/test*"
            localpath="D:\build\"
            comment="Modified by automatic build"/>

Checks in the file(s) named test* in the project $/test using the local directory D:\build.

vss:checkout

Description

Task to perform CHECKOUT commands to Microsoft Visual SourceSafe.

If you specify two or more attributes from version, date and label only one will be used in the order version, date, label.

Parameters

Attribute	Values	Required
vsspath	SourceSafe path which specifies the project/file(s) you wish to perform the action on.	Yes
login	username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password.	No
localpath	Override the working directory and get to the specified path	No
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
serverPath	directory where `srcsafe.ini` resides.	No
writable	true or false	No
recursive	true or false	No
version	a version number to get	No, only one of these allowed
date	a date stamp to get at
label	a label to get for
writablefiles	Behavior when local files are writable. Valid options are: `replace`, `skip` and `fail`; Defaults to `fail` `skip` implies `failonerror=false`	No
failonerror	Stop the buildprocess if ss.exe exits with a returncode of 100. Defaults to true	No
filetimestamp	Set the behavior for timestamps of local files. Valid options are `current`, `modified`, or `updated`. Defaults to `current`.	No
getlocalcopy	Set the behavior to retrieve local copies of the files. Defaults to true.	No

Examples

<vss:checkout vsspath="$/test"
             localpath="D:\build"
             recursive="true"
             login="me,mypass"/>

Does a recursive checkout of the project $/test to the directory D:\build.

vss:add

Description

Task to perform ADD commands to Microsoft Visual SourceSafe.

Parameters

Attribute	Values	Required
localpath	Specify the local file(s) to add to VSS	Yes
login	username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password.	No
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
serverPath	directory where `srcsafe.ini` resides.	No
writable	true or false	No
recursive	true or false	No
comment	Comment to use for the files that where checked in.	No
autoresponse	'Y', 'N' or empty. Specify how to reply to questions from VSS.	No
failonerror	Stop the buildprocess if ss.exe exits with a returncode of 100. Defaults to true	No

Examples

<vss:add localpath="D:\build\build.00012.zip"
            comment="Added by automatic build"/>

Add the file named build.00012.zip into the project current working directory (see vsscp).

vss:cp

Description

Task to perform CP (Change Project) commands to Microsoft Visual SourceSafe.

This task is typically used before a VssAdd in order to set the target project

Parameters

Attribute	Values	Required
vsspath	SourceSafe path which specifies the project you wish to make the current project.	Yes
login	username[,password] - The username and password needed to get access to VSS. Note that you may need to specify both (if you have a password) - Ant/VSS will hang if you leave the password out and VSS does not accept login without a password.	No
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
serverPath	directory where `srcsafe.ini` resides.	No
failonerror	Stop the buildprocess if ss.exe exits with a returncode of 100. Defaults to true	No

Examples

<vss:cp vsspath="$/Projects/ant"/>

Sets the current VSS project to $/Projects/ant.

vss:create

Description

Task to perform CREATE commands to Microsoft Visual Source Safe.

Creates a new project in VSS.

Parameters

Attribute	Values	Required
login	username,password	No
vsspath	SourceSafe path of project to be created	Yes
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
quiet	suppress output (off by default)	No
failOnError	fail if there is an error creating the project (true by default)	No
autoresponse	What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this.	No
comment	The comment to use for this label. Empty or '-' for no comment.	No

Examples

<vss:create vsspath="$/existingProject/newProject"/>

Creates the VSS-Project $/existingProject/newProject.

vss:destroy

Description

Task to perform DESTROY commands to Microsoft Visual Source Safe.

Permanently removes a project or file in VSS.

Parameters

Attribute	Values	Required
login	username,password	No
vsspath	SourceSafe path of project to be removed	Yes
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
quiet	suppress output (off by default)	No
failOnError	fail if there is an error creating the project (true by default)	No
autoresponse	What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this.	No

Examples

<vss:destroy vsspath="$/existingProject/oldProject"/>

Permanently removes the VSS-Project $/existingProject/oldProject.

vss:move

Description

Task to perform MOVE commands to Microsoft Visual Source Safe.

Moves a project or file in VSS.

Parameters

Attribute	Values	Required
login	username,password	No
vsspath	SourceSafe path of project to be moved	Yes
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
quiet	suppress output (off by default)	No
failOnError	fail if there is an error creating the project (true by default)	No
autoresponse	What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this.	No
destination	location in VSS to move project specified by vsspath to.	Yes

Examples

 <vss:move
  	  vsspath="$/${vss-project}/sub2"
	  destination="$/${vss-project}/sub1"
  	  login="Guest,"
  	/>

Moves the VSS-Project $/${vss-project}/sub2 to $/${vss-project}/sub1/sub2.

vss:cloak

Description

Task to perform CLOAK commands to Microsoft Visual Source Safe.

Hides a project from recursive Get, Check Out, Check In, Undo Check Out, and Project Differences commands.

Parameters

Attribute	Values	Required
login	username,password	No
vsspath	SourceSafe path of project to be cloaked	Yes
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
quiet	suppress output (off by default)	No

Examples

 <vss:cloak
  	  vsspath="$/${vss-project}"
  	  login="Guest,"
  	/>

Cloaks the VSS-Project $/${vss-project}.

vss:decloak

Description

Task to perform DECLOAK commands to Microsoft Visual Source Safe.

Removes the cloaked attribute from a project.

Parameters

Attribute	Values	Required
login	username,password	No
vsspath	SourceSafe path of project to be decloaked	Yes
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
quiet	suppress output (off by default)	No

Examples

 <vss:decloak
  	  vsspath="$/${vss-project}"
  	  login="Guest,"
  	/>

Decloaks the VSS-Project $/${vss-project}.

vss:delete

Description

Task to perform DELETE commands to Microsoft Visual Source Safe.

Removes files and projects from VSS Explorer, and marks them as deleted; the items still exist, however, and can be recovered using the Recover command.

Parameters

Attribute	Values	Required
login	username,password	No
vsspath	SourceSafe path of project or file to be deleted	Yes
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
quiet	suppress output (off by default)	No
failOnError	fail if there is an error creating the project (true by default)	No
autoresponse	What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this.	No

Examples

 <vss:delete
  	  vsspath="$/${vss-project}"
  	  login="Guest,"
  	/>

Deletes the VSS-Project $/${vss-project}.

vss:recover

Description

Task to perform RECOVER commands to Microsoft Visual Source Safe.

Recovers files and projects that have been deleted.

Parameters

Attribute	Values	Required
login	username,password	No
vsspath	SourceSafe path of project or file to be recovered	Yes
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
quiet	suppress output (off by default)	No
failOnError	fail if there is an error creating the project (true by default)	No
autoresponse	What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this.	No

Examples

 <vss:recover
  	  vsspath="$/${vss-project}"
  	  login="Guest,"
  	/>

Recovers the VSS-Project $/${vss-project}.

vss:locate

Description

Task to perform LOCATE commands to Microsoft Visual Source Safe.

Locates files and projects in VSS.

Parameters

Attribute	Values	Required
login	username,password	No
vsspath	SourceSafe path of project or file to be recovered	Yes
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
quiet	suppress output (off by default)	No
failOnError	fail if there is an error creating the project (true by default)	No
autoresponse	What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this.	No

Examples

 <vss:locate
  	  vsspath="$/${vss-project}"
  	  login="Guest,"
  	/>

Locates the VSS-Project $/${vss-project}.

vss:status

Description

Task to perform STATUS commands to Microsoft Visual Source Safe.

Shows check out information on files VSS.

Parameters

Attribute	Values	Required
login	username,password	No
user	The user to search for files for.	No
vsspath	SourceSafe path of project or file to be recovered	Yes
ssdir	directory where `ss.exe` resides. By default the task expects it to be in the PATH.	No
quiet	suppress output (off by default)	No
failOnError	fail if there is an error creating the project (true by default)	No
autoresponse	What to respond with (sets the -I option). By default, -I- is used; values of Y or N will be appended to this.	No

Examples

 <vss:status
	  vsspath="$/${vss-project}"
	  login="Guest,"
      user="Guest"
	/>

Locates the VSS-Project $/${vss-project}.

Microsoft Visual SourceSafe Tasks User Manual

Contents

Task Descriptions

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Specifying the time-frame

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples

Description

Parameters

Examples