Visual SourceSafe (VSS) is a client/server application which acts as a storage system for files.

A file stored in a VSS server is not available via the standard file system, instead, it must be
accessed through the VSS client tools - the VSS windows client, the VSS command-line tool,
or else some application which integrates with or emulates these client tools.

The following discussion refers to version 6.0d. It contains three types of section:

- Discussions of important concepts, headed like this.

- Walk-throughs of development scenarios, headed like this.

- Practical advice and best-practice, which...

...appears in shaded boxes.

VSS Database

A VSS Database is a single instance of a VSS server - it's the big black box into which files get
placed. All commands to VSS are directed towards a particular VSS Database, and wach
database maintains a SRCSAFE.INI file which contains configuration information.

VSS Project

A VSS Database is organised as a tree structure, with each of the nodes of the tree being a
VSS Project. Each database contains a single root project, which can branch (to a depth of 15
nodes) into sub-projects.

VSS Projects are misleadingly named; instead they should be thought of as directly analagous
to filesystem directories, being unordered collections of up to 8000 files of any type. To
illustrate this, note that where an application's source-code is organised into files that live in
subdirectories off the main directory, these subdirectories have to be mapped onto subprojects
of the application's main project directory.

Don't confuse Visual Studio 'projects' with Visual Sourcesafe 'projects'. The latter are more
like directories, or folders. In fact, if you just think Visual Sourcesafe 'folder' where the
documentation says Visual Sourcesafe 'project', it will be easier to follow.

Working Folder

Because the files stored in VSS are not directly exposed as files, development work on these
files takes place on local copies, which are first checked out of VSS, changed, then checked in
again. While a file is checked out of VSS, it is can be locked to other developers, preventing
file overwriting. VSS also retains historical information about a file's changes, so it is possible
to extract and use old versions of a file, or roll back unsuccessful changes.

The folder in which a user manipulates his local copy of VSS project files is known as his
'working folder'. Each user will often have a distinct, local working folder for each VSS project,
the details of which are held by the VSS client in its SS.INI file.

Each working folder also gets populated with a VSSVER.SCC file, which contains version
information about the files in that folder. This allows VSS quickly to determine whether or not
local files are synchronised with those stored in the VSS database.
If it is possible that the source-code for your application may contain hard-coded file paths, it
is important that developers' working folders are at the same location. One way of doing this
is to require each application's working folder to be at the root of a particular drive.

Building and Deployment

For non-web applications, their compilation and deployment is not under the control of VSS.
The process that builds and deploys an application needn't integrate with VSS except to
extract the latest instances of the files into a local directory where they can be manipulated as
required.

For web applications, VSS does support a 'deploy' command. This copies a project's files onto
a webserver, either directly or via FTP. However, for various reasons one might choose to use
other methods of deployment with web applications.

Development Scenario: A

Let's consider the situation in which two developers, UserA and UserB have to cooperatively
develop a non-web application, are coming completely fresh to VSS, and neither uses an IDE
to create the application.

In this scenario we shall assume that each developer has a development machine, and that
there is a development server which both of them can access. This gives us the following three
computers: DevelopmentUserA; DevelopmentUserB; DevelopmentServer

The first thing that needs to be done is for a VSS database to be installed on
DevelopmentServer, and the VSS client tools to be installed on the two development
machines. It's useful to know that the installation of VSS on DevelopmentServer sets up a
network share to the installation directory, and the VSS client tools are available for users to
install from there (this has the additional benefit that the client tools are set up with the
DevelopmentServer database as the default).

Next, the VSS database has to be set up with appropriate users. VSS handles its own
authentication, rather than integrating with Windows authentication (though file access is still
subject to NTFS permissions, of course), so it is necessary to set up individual accounts in VSS
for the two users.

Next, the application development should start, and the application files should be added to
the VSS database. We shall assume that these application files are stored on UserA's personal
development computer.

The advice from those with experience of developing using VSS is that before adding files to
the VSS database it is useful to progress the development to a stage where the general
structure of the application and its source code is mostly settled. This is because the process
of renaming and moving application files can raise various small problems.

As he is not using a VSS-integrated IDE, UserA will use the VSS client tool to add the
application file to the database. To do this, he will need to point the client tool at the
appropriate VSS database, which involves executing File -> Open SourceSafe Database and
navigating to the SRCSAFE.INI file on DevelopmentServer.

After identifying the appropriate database, the following procedure will add all of the
application source files to the database:

• select the root project ($/)

 • execute File -> Add Files

• navigate to the root directory of the application files (leaving the Relevant Masks at
*.*) and press Add

• add a descriptive comment, tick 'recursive', and press 'Add'

• agree to make the source directory the 'working directory' for the current project.

Alternatively, the required files may be dragged and dropped from Windows Explorer to the
appropriate VSS project. This takes you to point 4 above.

Once the files are in the VSS project, UserB will be able to view the project via the client tool.
When he tries to access these files, he will be prompted to nominate a local working directory,
and will be able to work on from that point.

Getting vs Checking Out

If you 'Get' a file / project (which you do using the client tools by right-clicking on the item
and selecting 'Get Latest Version'), a read-only copy is placed into your working folder.
Changes you make to this file cannot be subsequently uploaded to the VSS database.

On the other hand, when you 'Check out' a file / project (which you do analagously to 'getting'
it), a writable copy is placed into your working folder. By default, this locks the file to other
users, so that while they may 'Get' a copy of the file they cannot themselves check it out.
Notice that when you check out (and check in), you have the option to add a comment. This is
to help developers keep track of the file changes.

When either of these options is being applied to a project, the procedure can be applied
recursively, so that it is applied to subprojects of the chosen project.

Checking In

When you've finished making changes to a checked-out file / project, then you can check it in
again, which writes the file changes to the VSS database. This procedure is also effected in the
client tools using a right-click menu.

By checking project files out and in using VSS, developers can avoid the situation in which one
overwrites the changes made by another.

Note that there are a few restrictions on filenames in VSS; for instance, they cannot contain
the dollar sign ($).

Development Scenario: B

Let's now consider the situation in which our two developers have to cooperatively develop a
non-web application using Visual Studio .NET. In this case the VSS commands are integrated
with the IDE.

The recommended structure for a .NET solution is to locate each project folder under the
solution folder (which is not the default: often, you create a project along with its solution
files, and the two go into the same directory). It is easy to get the recommended structure
when creating the project – the important check box to tick when creating the solution /
project is revealed by clicking More, and reads Create directory for solution. Otherwise, it is
possible to set up a blank solution first and add the project into it.

Let's assume that the VSS database and the VSS users have been set up correctly. Then the
process of uploading the Visual Studio solution and its projects (recall that VS projects are
different kind of things to VSS projects) will go via:

File -> Source Control -> Add Solution To Source Control

or possibly

File -> Source Control -> Add Selected Projects To Source Control

This action will first prompt for a VSS database path and user credentials, then (recursively)
add one or more project to the chosen VSS database. It is possible to see the files uploaded to
the database via the VSS client tool (though we found it necessary to close and open up the
tool in order to see the added project – the refresh command did not seem effective).

Initially, the project files are in their checked-in state, demonstrated by a small blue padlock
on the left-hand side of their icons. As has been said previously, in this state the project files
cannot be amended. So a user who wants to amend a file has either to explicitly check it out
from Visual Studio using one of the many menus that support this functionality, or else just
attempt to edit it, which brings up a dialogue that helps him check it out. The checked-out
status of the file is indicated with a small red exclamation mark.

Note that the compiled project files do not get placed into the VSS database. The generation
and storage of these executables lies outside the purview of VSS. Furthermore, there are a
number of project files generated by Visual Studio which contain information specific to an
individual user, and these are not added to VSS either; such files have the extensions .suo,
.user or .webinfo.

This deals with how UserA adds a project to Visual Studio project to VSS, but then how does
UserB then access this existing project? The required command is:

File -> Source Control -> Open From Source Control

This then brings up a VSS dialogue box with the contained projects. When the user selects the
required project, he is asked to nominate a local directory, which is then set as the user's
project working folder.

Historically, people have had problems when attempting to share solution files (*.sln). It may
be easier for developers to maintain their own solution files, and just pull in the project from
VSS.

SS.exe

VSS also makes available a command-line program SS.exe to support its various functions.
The main use of this tool is to allow integration of VSS functions into applications which, unlike
Visual Studio, aren't integrated with VSS out of the box.

According to the VSS documentation, SS.exe “is usually in the Win32 subfolder under the
folder you choose in the setup program”. In our case, it was found at:

[D:\Program Files\Microsoft Visual Studio\Common\VSS\win32\SS.exe]

If you are going to make extensive use of SS.exe, you'll probably want to add its containing
directory to the environment PATH variable.

It may also be necessary / useful to add a couple of VSS-specific environment variables. The
first, SSUSER, relates to VSS authentication. According to the documentation, when the
command-line tool is used, VSS picks up the user's logon name and tries to authenticate using
that (apparently ignoring the password, which makes you wonder why it's there at all). If the
VSS username is not the same as one's NT logon name, however, one can put the VSS
username in the SSUSER environment variable, and this is used instead (again, without any
password).

Note that in order to access the VSS database in the first place, users will have to have an NT
login with appropriate access permissions. The authentication provided by VSS lives on top of
standard Windows security.

The second environment variable, SSDIR, is used to inform SS.exe which VSS database it
should use. If you install the client tools via the executable provided on the server hosting the
database, then this may be set automatically to point to that database. Otherwise, you will
probably need to set it up automatically. In our case the setting looks like:

SSDIR = \\nwk-s-web\sourcesafe\

Development Scenario: C

Let's consider the situation in which two developers are using a basic development tool like
Textpad to develop a non-web application. One way in which they could proceed is to use the
VSS client tool to check files in and out. But a prefered alternative might be to write a macro
(or possibly, for Textpad, a 'user defined tool') utilising SS.exe.

There is no point in going through exactly how this is done in Textpad. Instead we'll take a
quick look at the kind of SS.exe commands that would be used.

First, we should note that the command-line tool is able to keep track of the 'current project'
across commands (recall that for VSS a project is an element in a hierarchy). The following
command sets this current project to 'tempProject.root' - note the dollar sign and the forward
slash in the code (the latter of which indicates that tempProject.root is itself located at the
database root).

ss cp $/tempProject.root

The following command checks out the file tempProject.sln from VSS:

ss Checkout $tempProject/tempProject.sln

There are two important points to note about this. Firstly, we are identifying the file we want
by providing a virtual path. Because we previously set the current project to be equal to

$/tempProject.root

the virtual path resolves – in the familiar way – to

$/tempProject.root/tempProject/tempProject.sln
The second point is that the command does not place the checked out files in any working
folder that might have previously been specified for this project. Instead it places the files in
the folder in which the user executes the command.

We can also check out project files recursively, which creates the appropriate local subfolders.
For example, the following command (which uses an absolute project path) checks out all of
project and subproject files under tempProject.root:

ss Checkout $/tempProject -R

(For some reason, if you don't provide the project / file path in the Checkout command it asks
you to enter one, but then takes the current project setting if you press enter.)

Checking files in works in an analagous way, but uses the 'Checkin' command, eg.

ss Checkin -R

Getting (recursively) the latest version of project files is equally straightforward:

ss Get -R

Multiple Checkouts

By default, if you check out a file then no other user can check it out until you've checked it
back in: the file becomes locked to changes by anyone other than you. But the VSS
administrator may enable 'multiple checkouts', which (fairly obviously) allows multiple users
simultaneously to check out files.

So, what happens when UserA and UserB each checks out a file to his local working folder,
each updates it independently, and then each tries in turn to check it back in? What needs to
be avoided here, obviously, is UserA's changes being overwritten by UserB's check-in. What
VSS tries to do is to merge each user's changes into the master copy. This is easiest if users
have made small changes to different parts of the file. However, if users have each changed
the same part of the file then merging is not possible, so VSS rejects UserB's check-in
attempt, with appropriate information about the problem, and requires him to resolve the
conflict.

The people that I’ve talked to about this, who have been using VSS from its earliest versions,
recommend against using multiple checkouts. They claim that the merging algorithm isn’t
100% solid, and that there are management benefits to knowing exactly who is currently
working on a file. However, it may be that where development involves a large, geographically
distributed group of people that communication problems would offset any problems with
multiple checkouts.

Web Deployment Models for VS.NET

The MSDN article Web Projects and Source Control Integration in Visual Studio.NET provides
three useful models for collaboratively developing websites (in VS.NET, but the models are
useful beyond this). The models differ crucially in where each developer can run and test
changes. In each case the deployment of the production website from a latest version is
independent of the model.

- Isolated Development
In this model, all developers maintain a working copy of the website on their own development
machine (which must therefore be running web server software). Latest versions of the code
can be brought down from VSS in the familiar way. This is the recommended development
model.

- Semi-Isolated Development

In this model, all developers share a single development web server, such that each has a
distinct working folder on that server. While users share a webserver, therefore, each user
maintains his own copy of the web application. Latest versions of the code are brought down
from VSS to these working folders.

One of the disadvantages of this model is that the debugging process freezes all the
applications on the website, so at most one user can test / debug at a time.

- Non-Isolated Development

In this model, there is a single development web server, but developers must access the
master copy of the code using FrontPage Extensions. Here developers both share a web server
and share a copy of the web application (although they may be able to download the files to
local machines, when the developers run and test changes they are using the same code). In
order for there to be VSS integration, the website needs to be a FrontPage web project (which
can be set to integrate with VSS).

Development Scenario: D

Let's look at the situation where our two developers are creating a simple ASP.NET website
with VS.NET. I shall assume that they use the 'isolated' development model.

When you create a new ASP.NET web application in VS.NET, the default location for the project
files lies somewhere under the root folder of the default website, which will probably be
something like this:

C:\inetpub\wwwroot

On the other hand, the location of the solution file is likely to be elsewhere. But Microsoft
recommends that the solution file should be stored in a folder above the root project folder.
The way round this problem is to create a blank solution located at a certain folder, then map
a folder below it as a new virtual IIS directory, and use this virtual directory as the location for
the web application.

So, let us suppose that DevelopmentUser A starts off by creating a blank solution, locating it
at:

C:\Solutions\TestSolution1

He then creates a new folder

C:\Solutions\TestSolution1\TestProject1

maps this to the IIS virtual directory

http://localhost/TestProject1
and creates the new project TestProject1, locating it in this virtual directory.

To add this to VSS, DevelopmentUserA uses the standard command:

File -> Source Control -> Add Solution To Source Control

DevelopmentUserA ignores the warning that he will no longer be able to open the project
using FrontPage Web access - accessing web projects using File Access is preferable where this
is possible (basically this means that VS.NET just accesses the project files using the file
system, rather than getting them from IIS via Frontpage Extensions). In the next dialogue
boxes he enters the appropriate credentials to place the solution in the VSS database with the
appropriate name, and the job is done.

According to the Microsoft document Team Development with Visual Studio.NET and Visual
SourceSafe, the project structure in VSS should mirror the file structure in the working folder.
But VS.NET seems very keen to place solution files in VSS projects parallel to those containing
VS.NET project files. It is possible to manually move these folders in VSS, and then tell
VS.NET about the move, but it's not clear why this is important.

Web Projects

VSS distinguishes between standard and 'web' projects. For the latter it has introduced –
albeit in a fairly half-hearted way – some specific tools. So, for instance, there is a facility to
create a site map, hyperlink checking, and some keyword expansion. Furthermore, there is
also a 'deploy' command, which seems just to copy all the project files to location via FTP.

Sharing and Branching Files

It is possible to 'share' files between projects, so that there is a single master copy which
appears in different places in the VSS project tree structure. Changes made to this copy from
within one project will be seen in the other projects that share the file.

Right-clicking on a folder within VSS Explorer, or using the File -> Source Control menu
VS.NET brings up the Share dialogue, from which one can choose files to share.

I have been informed that sharing of files can cause problems. In particular, the following
scenario: a file is shared between projects A and B. It is checked out as part of project A but
then by mistake checked back in as part of project B. (Exactly what problems this caused was
left unspecified by my correspondent, but they seemed severe enough to warrant a warning).

Rolling Back

VSS maintains a history of changes to files, so that it is possible to roll back files to previous
versions. From VSS Explorer you right-click the file and choose 'History', from which you can
see a history of changes to the file along with possible actions. From VS.NET you use the File
-> Source Control menu.

It doesn't look like it's possible to roll a whole project back to a previously known good point,
however.

By default, rolling back a file erases all of the file history past that point. However, it is
possible to perform a 'virtual rollback', in which the file history is not deleted.
Where files are shared between projects, rolling back a file from one project will result in the
files branching.

Showing Differences

The VSS client tool is able to display the differences between different versions of text files,
which can be useful for debugging purposes.

Pinning

It is possible to pin files so that they can't be changed (at least without first being unpinned).

Labelling

As well as commenting actions, users can add labels to files or projects. In the VSS client tool
this is effected by right clicking or using File -> Label…

Labelling files is useful for marking certain versions as important. For instance, a project might
be labelled as 'Release Candidate 1', and if one wanted to extract that version at a later date,
then one could look for the label. Note that when a label is applied to an object, a separate
entry is created within the history of that object.

Cloaking

Where an operation like 'Get' is used recursively, the operation is applied to all of the
subprojects (in this case we can say that it is applied 'indirectly'). If a user wishes to turn this
behaviour off for his own recursive operations, he can mark the subproject as 'cloaked'.
Subprojects so marked won't have operations applied to them indirectly. They may still be
usable directly, however.

Shadow Folders

A shadow folder is a nominated file directory which is kept up to date with copies of the most
recent files in a VSS project, the idea being that this folder can be used to compile latest
versions of code. Unfortunately, however, the updating process is not recursive.