# Microsoft Visual SourceSafe Tasks User Manual

by

- 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

## Contents

- Introduction
- The Tasks

## Introduction

These tasks provide an interface to the Microsoft Visual SourceSafe SCM. The `org.apache.tools.ant.taskdefs.optional.vss` package consists of a simple framework to support VSS functionality as well as some Apache Ant tasks encapsulating frequently used VSS commands. Although it is possible to use these commands on the desktop, they were primarily intended to be used by automated build systems.

If you get a `CreateProcess error=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.

## The Tasks

Task | Description
--- | ---
vssget | Retrieves a copy of the specified VSS file(s).
vsslabel | Assigns a label to the specified version or current version of a file or project.
vsshistory | Shows the history of a file or project in VSS.
vsscheckin | Updates VSS with changes made to a checked out file, and unlocks the VSS master copy.
vsscheckout | Copies a file from the current project to the current folder, for the purpose of editing.
vssadd | Adds a new file into the VSS Archive
vsscp | Change the current project being used in VSS
vsscreate | Creates a project in VSS.

## Task Descriptions

## VssGet

### 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. | No; by default expected to be in `PATH`
serverPath | directory where `srcsafe.ini` resides. | No
writable | true|false | No; default false
recursive | true|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 get will always be done recursively | No; default false
version | a version number to get | No; only one of these may be used
date | a date stamp to get at
label | a label to get for
quiet | suppress output | No; defaults to off
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; skip implies failonerror=false | No; defaults to fail
failonerror | Stop the build process if `ss.exe` exits with a return code 100 | No; defaults to true
filetimestamp | Set the behavior for timestamps of local files. Valid options are current, modified, or updated. | No; defaults to current

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

### Examples

Perform a get on the VSS Project `$/source/myproject` using the username me and the password mypassword. That 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.

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

## VssLabel

### 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. | No; by default expected to be in `PATH`
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 build process if `ss.exe` exits with a return code 100. | No; defaults to true

### Examples

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

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

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

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

## VssHistory

### 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. | No; by default expected to be in `PATH`
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. | No; defaults to `DateFormat.SHORT`
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|false | No
style | brief, codediff, default or nofile. | No; defaults to default
user | Name the user whose changes we would like to see | No
failonerror | Stop the build process if `ss.exe` exits with a return code 100 | No; defaults to true

#### 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

Show all changes between Release1 and Release2.

    <vsshistory vsspath="$/myProject" recursive="true"
                fromLabel="Release1"
                toLabel="Release2"/>

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

    <vsshistory vsspath="$/myProject" recursive="true"
                fromDate="01.01.2001"
                toDate="31.03.2001"/>

Shows all changes in the last fortnight.

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

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

## VssCheckin

### 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. | No; by default expected to be in `PATH`
serverPath | directory where `srcsafe.ini` resides. | No
writable | true|false | No
recursive | true|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 build process if `ss.exe` exits with a return code 100. | No; defaults to true

### Examples

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

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

## VssCheckout

### 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. | No; by default expected to be in `PATH`
serverPath | directory where `srcsafe.ini` resides. | No
writable | true|false | No
recursive | true|false | No
version | a version number to get | No; only one of these may be used
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; skip implies failonerror=false | No; defaults to fail
failonerror | Stop the build process if `ss.exe` exits with a return code 100. | No; defaults to true
filetimestamp | Set the behavior for timestamps of local files. Valid options are current, modified, or updated. | No; defaults to current
getlocalcopy | Set the behavior to retrieve local copies of the files. | No; defaults to true

### Examples

Check out the project `$/test` recursively to the directory `D:\build`.

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

## VssAdd

### 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. | No; by default expected to be in `PATH`
serverPath | directory where `srcsafe.ini` resides. | No
writable | true|false | No
recursive | true|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 build process if `ss.exe` exits with a return code 100. | No; defaults to true

### Examples

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

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

## VssCp

### 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. | No; by default expected to be in `PATH`
serverPath | directory where `srcsafe.ini` resides. | No
failonerror | Stop the build process if `ss.exe` exits with a return code 100. | No; defaults to true

### Examples

Set the current VSS project to `$/Projects/ant`.

    <vsscp vsspath="$/Projects/ant"/>

## VssCreate

### 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. | No; by default expected to be in `PATH`
quiet | suppress output | No; defaults to off
failOnError | fail if there is an error creating the project. | No; defaults to true
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

Create the VSS Project `$/existingProject/newProject`.

    <vsscreate vsspath="$/existingProject/newProject"/>