Due to changes in our project's structure, file locations shown in several of the following images are outdated and incorrect. Please just use the images as a tool in understanding the general concept the text is trying to get across. The text of this document is current as of its last revision.
Microsoft Visual Source Safe can be started in one of two modes: as a user/client or as an administrator. This page focuses only Source Safe's user mode; see the page on administration for details on using Source Safe in adminstative mode. To load Source Safe in user mode, run the executable "Ssexp.exe" located in the "/vss/win32/" subdirectory of our NT group directory. I recommend creating a shortcut from your desktop for convenience.
After running the executable, the Source Safe main window is displayed:
The left window pane shows the name of the current folder, and subfolders can be shown or hidden by clicking on the "+" sign. The right window pane dispays the files (and not subfolders) contained in the current folder. The bottom window pane is used to display messages to the user. Also note that your name is displayed in the bottom center of the window; Source Safe always knows which users are running it so that when a file is checked out it can indicate who it was that checked out the file.
Note the folder "$/" in the left window pane. This is SourceSafe's hardcoded superfolder which contains all of our files and directories as subfolders.
Before we began using Source Safe, all of our files were saved directly in our NT group directory; editting html source then meant opening a file located there. But when our source was checked into Source Safe, all of those files were deleted since Source Safe does not store actual files, but rather database entries representing those files. In order to edit these files now, you need to load Source Safe and use the "Get Lastest Version" command, which will use the database entries corresponding to our files to recreate the actual files, placing read-only copies of them into a personal NT subdirectory you should create off of the "/Users" subdirectory of our NT group directory. You should remove group access to this directory so that only you can access it; the reasons for this will become apparent after reading the "CHECKING FILES IN AND OUT" section later on.
To get the latest versions of all files under source control. right-click on the "$/" superfolder in the left window pane and select, "Get Latest Version":
Note in the upper right hand corner of the window the message "No Working Folder"; Source Safe does not yet know the location you want the files to be copied to, as the following message indicates:
Select "Okay". If you have not yet created your personal subdirectory as described earlier, you should do so now. Select this personal directory as your Working Folder.:
Select "OK". Now that you have set your working folder, Source Safe will save this information in our NT shared directory under "/Vss/Users/YourUserName/ss.ini" so that you should never need to specify it again. From now on I will refer to your Working Folder and this private directory interchangeably. Next we see the following window:
Select "Recursive" so that you get a copy of all files in the project. This is also causes the "Make writable" option to be automatically disabled so that you get read-only copies of all files. The only time you would ever need to select "Build tree" is if you had specified a different Working Folder for a subfolder of the project and wanted to override this setting. In general, NEVER SET A DIFFERENT WORKING FOLDER FOR A SUBDIRECTORY OF "$/"; it cannot be undone without hacking your "ss.ini" file.
Select "OK" to execute the "get". You will then see the following:
The bottom window contains the names of all the files that were copied to your "Working Folder", which you can see is now specified in the upper-right hand corner of the above window. At this point all files have been copied to your "Working Folder".
Each time you begin a work session, the first thing you should ALWAYS do is to do a "get" on the project so that you always have a current version of all files before you begin working.
Recall that doing a "get" gives us read-only copies of all files. In order to actually edit a file we need to check it out from Source Safe. When you check a file out, not only does it give you write permission on the appropriate file in your Working Folder, but it also indicates to the other members of the project in the Source Safe main window that the file is checked out to you and prevents them from being able to check out the file at the same time as you; this way we avoid two people editting the same file simultaneously and the problems which go along with it. Hopefully you now see why you must use for your Working Folder a directory which only you have access to: whenever you check out a file, you want to be the only one who can edit it, but if you were to choose a Working Folder that was accessible to the group, then whenever you checked out a file anyone could modify it, which would be very very bad! As a final note, when you want to edit a file, you must check it out with Source Safe rather than use Explorer or DOS to give yourself write permission for it; doing so would simply result in Source Safe seeing a discrepency between your file and its database, erasing your modified file, and replacing it with its latest version of the file, which would also be very bad!
To check one or more files/directories, select them and then select "Check out" from the "SourceSafe" pull-down menu:
After which you will see the document highlighted in red with a checkmark to inicate the file has been checked out. The name of the user who checked out the file is listed in the second column of the right window pane:
When you are done editting the file, the next step is to check it back in to Source Safe. This makes the file read-only again for you and also makes it so that others can check out the file now that you are done with it. To do this, highlight the file and select "CheckIn" from the "SourceSafe" pull-down menu:
You will then see the following window:
ALWAYS enter a comment before checking the file in order to document the changes you have made, both for others and yourself as you WILL forget after enough time has passed; this way we can use Source Safe to self-document our project and cut down the amount of external documentation we need to keep.
Selecting "Keep checked out" updates SourceSafe's version of the file while keeping the file checked out to you. You might want to select this option if you've already made a number of changes and want to make sure your work is not lost, yet still have more changes to make (basically backing up your file). For now we'll just select "OK". SourceSafe's version of the file has now been updated with the editted file and the checkmark and highlighting has been removed to indicate the file is now availiable for check out by anyone.
Sometimes when you have a file checked out you might make a mistake editting it which cannot be undone; in this case it would be nice to discard the version of the file checked out to you and go back and get the last version of the file before you checked it out. This can be accomplished by "undo-ing" your check out. From the "SourceSafe" pull-down menu:
Source Safe will then prompt you for confirmation:
Select "OK" and Source Safe will undo your check out and replace your version of the file with the most recent version in the database.
When you want to create a new file, do so inside of the appropriate subdirectory of your Working Folder. Then, to add a file/directory to the Source Safe project, select "Add files" from the "File" pull-down menu:
You will then see a window like the following one.
For adding files, simply find the file you want to add to the project and select "Add". Adding subdirectories is more tricky and could cause undesired results if done incorrectly. To add a subdirectory, enter inside of the subdirectory, select the "Relevant Masks (*.*)" file mask, and then select "Add"; the trick here is knowing that the parent directory is always added as well whenever you add a subdirectory in this fashion, and since we're inside the subdirectory, the parent directory is the subdirectory, thus it accomplishes what we want it to. IMPORTANT: Never try to add a subdirectory by simply highlighting it from the outside and selecting "Add"; this will result in the full virtual path of the directory being added to the project, which is not what we want.
You will be prompted for a comment. Write a short description of what the file is, what is being used for, if an image which html file is using it, etc. (this way we can just use source safe to self-document our project without having to write up any external documentation):
Select "OK". The file is now in the project. The previous window now appears again as Source Safe is asking if you have any more files to add. Select "Close" to indicate you are done adding files. Note that our file now appears in the directory we added it to!
IMPORTANT
To remove one of more files/directories from the project, highlight the given file in the right window pane and select "Delete" from the "File" pull-down menu.
Next, Source Safe asks you to confirm the delete. Notice the box in the window: "Destory permanently"; NEVER EVER EVER select this option. When a file is deleted normally, the file is removed from the project but still stored in the database so that it could always be recovered; this is similar to the purpose of Windows' Recycle Bin and Macintosh's Trash Can. Selecting "Destroy permanently", on the other hand, removes the file from the project AND removes it from the database, hence the file can never be recovered. If we later decided we needed the file after all, it would mean recreating the file from scratch, and we never want to have to do the same work over again; this would be a waste of our time. In the case that we eventually run into a shortage of disk space, we can always purge old, deleted files from the database later on.
Leave "Destory permanently" unchecked and select "OK".
You'll see the file is now no longer in the project.
Destroyed files cannot be recovered. To recover a deleted file that was not destroyed, highlight the directory which contained the file and select "Properties":
The following window now appears:
To recover the file (add it back to the project) simply select "Recover". Note: you will not be prompted for confirmation. Select "Recover" and you should see the files immediately appear in the directory in the right window pane of the main Source Safe window.
Purging files: it should never happen, but in the case we run into a shortage of disk space AND there are a number of old, unused files lingering in the database AND EVERYONE agrees these files will never be used, only then might one want to use this option for those files. To remove the files permanently, highlight the selected files and select "Purge". You will then be prompted for confirmation:
Purging is the same as selecting "Destroy permanently" when deleting file: once the file is purged, it can never be recovered. Select "Yes" if you are sure you want to purge the selected files. Note: SourceSafe has been setup so that only Gaetano has "destroy" rights, hence only he can purge files.
Sometimes you might want to check what changes the last person made who checked in a given file. This could mean simply viewing the comment they wrote describing what they did, or it could mean doing an actual file comparision between two versions of the file. On a different tangent, you might want to view the details of the original check in to see what the file was intended to be used for. Then again, you might want to see the entire evolution of a file since its original check in. All of this can be accomplished quite easily in Source Safe.
Begin by highlighting the file in question and from the "Tools" pull-down menu select "Show History":
You will then see the following window:
If you would simply like to view a particular version of the file, highlight the given version and select "View"; the system's default browser will be spawned and loaded with the given version of the file:
If you would like to view the comments entered when a particular version of the file was checked-in, highlight the given file and select "Details":
Inside the window pane "Comment:" you would see whatever information describing the changes made between this version and former as entered by the person who checked in this version of the file. If you wanted to name this version of the file (i.e. "Beta" or something) you could enter that in the "Label:" area.
Returning to the history window, if you wanted to view the evolution between several, highlight the given versions of the file and select "Report":
You will then see the following:
You can output the repor to the printer, file, or clipboard and optionally include the comments entered when ever each version was checked in and or view the difference between each version. The following is a sample output:
$/DDOR/Home.html
***************** Version 2 *****************
User: Mlease Date: 3/08/97 Time: 6:08p
Checked in $/DDOR
Comment:
Changes:
10 Change: <CENTER><ADDRESS><A HREF="http://www.cs.washington.edu/"><IMG SRC="http://www.cs.washington.edu/education/courses/142/icons/nameplate_small.old.gif" BORDER=0 HEIGHT=62 WIDTH=325></A></ADDRESS></CENTER>
To: <CENTER><ADDRESS>asdfasdf<A HREF="http://www.cs.washington.edu/"><IMG SRC="http://www.cs.washington.edu/education/courses/142/icons/nameplate_small.old.gif" BORDER=0 HEIGHT=62 WIDTH=325></A></ADDRESS></CENTER>
***************** Version 1 *****************
User: Mlease Date: 3/08/97 Time: 4:26p
Created Home.html
Comment:
Of course this is a rather messy way to do a file comparison when Source Safe offers a much nicer one. Returning the main history window, you can do a graphical line by line file comparision between two versions of a file by highlight the given versions and selecting "Diff":
The following window will then open:
You can now scroll through the two versions and see what, if any lines in the former version were deleted (shown in blue), any lines changed (shown in red) and any lined added (shown in green).