Microsoft Visual SourceSafe Tasks User Manual

by


Contents


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:

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}.


Copyright © 2000-2006 The Apache Software Foundation. All rights Reserved.