This tutorial is the first part in a two part series on how to use Visual SourceSafe, a utility created by Microsoft, used for version control management. This first tutorial will cover the basics of VSS...what it is, how it can be used, and how to do the basic things with it.

Contents

There are a couple of prerequisites that I'm going to assume you have setup on your computer:

• VSS 6.0 installed. Obviously you need this to use it.... This was included on my copy of Visual Studio 6.0 (Enterprise Edition). I'm not sure if it's included in the Professional or Learning editions, but if not, you can probably buy or acquire it separately.
• Visual Basic 6.0 installed. In this tutorial, I will try to show you how to integrate VSS with the VB6 IDE (Interactive Development Environment). If you don't have VB6, it might work the same with VB5, but I don't know...

What is VSS?

• VSS is short for Visual SourceSafe. It's Microsoft's version management software.
• It is responsible for storing your code in a central repository (or database), and keeping track of changes to it.
• The premise behind VSS is that for each change, you "check out" the source code, make the changes, and then "check in" the code. In this way VSS keeps track of what changes have been made to your code over time.
• It is also great for environments where there is more than one user. It keeps track of who checked what in, who has what checked out, and when/why things were changed.

Why choose VSS?

• When you install VSS, it automatically comes with an Admin user. This is the "superuser" that has no access limitations or anything like that. This user is able to do whatever they want to the repository.
• You should never user the Admin user for anything other than administrative tasks. This is the same thing as never using the "root" user on unix systems as a regular user. The security is there to protect you from not making really bad mistakes.
• For each user in the development group (or just yourself if you're a "lone wolf"), you must create users for VSS. This is done using the Visual SourceSafe 6.0 Admin EXE (located at "C:\Program Files\Microsoft Visual Studio\Common\VSS\win32\SSADMIN.EXE" on my computer...). Note: The install should have created an icon for this program for you to use.
• When there, you add users through the Users->Add Users menu item. Here you enter the login name and password for the user you're creating.
• You will also have to assign the Admin a password. VSS leaves this blank as a installation default, so change it to something that only you know. This is done by selecting the Admin user, and using the Users->Change Password menu item.
• After you have added the users, you will want to assign them rights (what they are allowed to do to the code). This is done under the Tools->Rights Assignment for the User menu item. The rights are fairly self-explanatory, but I would suggest not giving "Destroy" rights to anyone...reserve this as only a Admin responsibility.
• Now that you have users, when you use the VSS EXE (called the VSS Explorer), you type in your user name and password, and it will log you into the repository as that user.
• If you want to create separate icons for each developer, just copy the main VSS shortcut, and edit the command line to have a "-Y<user>,<password>" at the end. Note: If you create a separate VSS icon for you to log in as the admin, don't put the password in the shortcut, since it's then in plain text.
• See the Tips and Tricks section for how to make it easier to login to VSS.

• So now you got your development team all entered, but you still have to initially enter your code into the database.
• Like I said before, this is one place where VSS makes things easy. All you have to do, is after you have VSS installed and your users set up, simply open up an existing project, and a dialog box will come up, asking if you want to add this project to SourceSafe. Just click "yes" and then follow the next few prompts, and wallah...your project has just been checked in.
• If you create a new project in VB, when you save, again the prompt will come up and you can click "yes" there, and it will be checked in.
• If you accidentaly click "no", the prompt will not come up again. However, you can still check your project in using one of two methods.
  1. Go to the project's folder on your hard drive, and delete the "Mssccprj.scc" file. This is the file that controls whether the IDE should check for a VSS link. Next time you then open that project, you will get the prompt again.
  2. Open up VSS (not the Admin program, but the actual VSS program (it's located at "C:\Program Files\Microsoft Visual Studio\Common\VSS\win32\SSEXP.EXE" on my computer)) and add the project manually. This is by creating a project (File->Create Project), selecting it in the treeview, and then adding the project files to it (File->Add Files). You can also use this method to add bitmaps and non-VB stuff to projects that aren't handled automatically by the VB IDE.

• Okay, so you'll probably never willingly delete a project (after all, even the smallest program is an accomplishment sometimes...), but it is nice to know something about it (perhaps if one was deleted by accident).
• Any user can delete a project if they have the "Add/Rename/Delete" user right. However, if you did like I suggested above, only the Admin user can actually permanently destroy a project.
• To delete a project, simply select that project in the VSS Explorer, and delete it using the File->Delete menu item. A prompt will come up asking you to confirm your decision. There is also a toggle that is visible to destroy it permanently or not. Only users with the "Destroy" user-right will be able to destroy it permanently.
• So if one of the normal users deletes a project, it must then be either Purged (permanently destroyed) or Recovered by the Admin. This is fairly easy to do...simply log into VSS as the Admin, right click the root project of the project that was deleted, go to the "Deleted Items" tab, select the project, and then click either Recover or Purge.

In this example (wow...a graphic! I'm going all out this time...), I deleted a test project which was located under the root ($/):

• Like I said earlier, the basic way you operate VSS, is to check out whatever file you want to make changes to, make the changes, and then check it back in.
• What makes VSS so great, as compared to other version control software, is how it integrates with the VB IDE.
• When you open up a project with version control, and look at the Project Explorer, you might see something like this:

This is a regular SDI form. [Not Checked Out] This is an MDI-child form. [Checked Out] This is an MDI-child form. [Not Checked Out] This is an MDI-parent form. [Not Checked Out] This is a regular module. [Not Checked Out] This is a module that is shared between applications (see part two of the tutorials for more information on this). [Not Checked Out] This is a regular class module. [Not Checked Out]

• When you right click on one of these items, the following options appear (the bottom four are specific to the VSS extension):

Get Latest Version - This will retrieve the latest version of the file that you have selected. This is fairly important if you are working in a development team. If someone else changes the code for one of the files, you have to invoke this option to get the latest version of it. You don't need to do this, however, if you are checking it out... it's then automatically done for you. Check Out - Fairly self explanatory. This checks the file out from the repository, and enables you to make changes to it. After clicking this, the icon in the Project Explorer should have a small red check beside it. Check In - When you are done making your changes, you select this option to store the code back into the database. After clicking this, a dialog comes up asking you to enter a description for the change, and some other options. This is also where you can view the changes that you've made to the module (by clicking the Differences button on the dialog box). Undo Check Out - This allows you to undo your checkout. If you've screwed up royally, and can't figure out what you've done by examining the Differences between versions, then you can always undo any changes you've done. By selecting this option, it basically reverts the file back to the previous version, and keeps no record that you ever had it checked out.

• You can also perform other actions, by using the Tools->SourceSafe menu. One of the more interesting ones, is Show History. This shows the version history for whatever file you have selected in the Project Explorer:

• In this case, I've "checked out - made changes - checked back in", 13 times for this file (okay, so I have a slight problem with making my mind up...).
• If you select one of the versions and then click Details, it will show whatever description was entered when the file was checked in
• If you click two different versions and then click Diff, it will show you the differences between the two versions of the files. This is extremely useful for tracking down bugs (i.e. it never did it in the old version, but it does it in the new version, so whatever changed must have caused the error (well, not all the time, but most of the time anyway)).
• You can generate a report for the versions, using the Report button. If you make a habit of printing a report out for every release, it's a good way to organize your project.

• You can set different options for how VSS interacts with the VB IDE, by clicking the Tools->SourceSafe->Options menu item:

All of the options can be either 'Yes', 'No', or 'Ask':

• Get latest checked... - This indicates if you want to get the latest version of the files when you open a project. It's a good idea to have this set to 'Yes', since you never have to do it manually then. One problem, is if you have a file checked out, and then open the VB project, it will prompt you if you want to replace the file you have checked out (which you probably don't want to do). To avoid this little pain, hit the Advanced button on this dialog, go to the Local Files tab, and set the Replace Writable Files option to 'Skip'.

• Check in files... - This indicates if you want to automatically check your files in when you close the VB project. You probably want this to 'No'...this could be especially annoying when you are creating a new file for the project (see Tips and Tricks).

• The VSS Explorer is the are where you can view the status of the project, and do other advanced things with it (some of these will be covered in part two of the tutorial).
• When you open up the VSS Explorer, you might see something like this:

• The treeview on the left hand side shows you all of your projects that you have in SourceSafe.
• The listview on the right hand side shows you all the files and their status for the selected project. As you can see, I have the frmBinary from checked out for the DirectFont project.
• You might notice that there are more files than you see when you open up the project in VB. This is because most forms also have a .frx, which contains specific binary information for the form. This is another plus about VSS...it handles this automatically for us (i.e. we don't have to check out both manually). For this reason, you probably don't want to check out forms manually (it's really easy to screw things up...)

• All of the things that you can do through the VB IDE, you can do here as well (Get Latest Version, Check In, Check Out, Undo Check Out, Show History, etc.)...simply right click on the item and perform the action.
• One thing that should be done through VSS Explorer is rolling back. A rollback is when you've made a really big mistake, and you want to revert to a previously saved version of the file. There are two ways of doing this, and which one to use is dependant on the situation.
  1. Hard Rollback - This is when you completely wipe out previous versions to get to the version you want. Say, for example, you are on version 13 of a file, and you want to rollback to version 5. After a hard rollback, versions 6-13 would be completely lost (so only use this option if you are absolutely sure that you will not ever need these versions of the files). To do this, log into VSS as the Admin, select the file that you want to rollback. Right click and pick Show History, and then select what version you want to rollback to (in our example, it would be version 5). Then simply press the Rollback button.
  2. Virtual Rollback - This is when you want to revert back, but you don't want to delete the previous versions. Using our previous scenario, instead of wiping out versions 6-13 to get to versions 5, you would check in the code from version 5 as a new version 14. This is a bit more complicated, but can be done by anyone (not just an Admin). It is better to do this within the VSS Explorer, because you have to manually do the .frx files for forms as well (things might get screwed up otherwise). Check out the file(s) that you want to revert. Show the history for the desired file, and then select the version that you want to revert back to. While holding the SHIFT key, click the Get button. A dialog box will come up asking what options you want to use for the Get. Click the Advanced button, and change the Replace Writable option to 'Replace' (Note: This does not affect your global preference). Then click OK to get the version...a message should come up in the bottom pane saying that the file was replaced. Now check in the code with an appropriate comment.

• When you create a user, if you create a user with the same login as the Windows logon and with no password, it won't prompt you for the name when you log into VSS. This could be semi-useful if your development team uses one computer for development, but multiple accounts on it.
• If you want to specify a different logon name, but still have no dialog come up, then define the SSUSER environment variable (do this in your AUTOEXEC.BAT) to your login name. This only works, though if you haven't specified a password.

• If you are creating a new file for your project, add it initially into SourceSafe before you add any code to it. Then you check it out, and do a lofty amount of code before you check it back it for the second time (i.e. get it so that it is somewhat working). However, if in the middle of creating it, you decide to completely revamp it, I would check it in at that point, so you can easily revert back.
• If you are modifying an existing file within the project (more common), whether it be to fix a bug, or to add an enhancement, check it in more frequently. Because you already have the base of code there, it makes it easier to see what you've done if you check in more frequently (because then each version that you check in, has smaller amounts of changes).
• Before you check your files in, make sure that the project compiles (if you need to get the latest version of all the files, click Tools->SourceSafe->Get Latest Version, and click Select All). This is very important...where I used to work, we configured VSS to rebuild the projects nightly (see part two of this tutorial for more information on how to do this). If one of use broke the nightly build, we had to buy beers for all the developers (~30 people), so we learned the hard way!
• When you check files in, whether it be for the first time or to add something, always add comments. The dialog boxes that pop up, always give you opportunity to add these, and they are very important. I just use it as a summary...I try to explain what I fixed, and why I changed it. I also always put my name and the date within the comment (usually at the end, like "Matt Budd - Dec 19, 2000"), so it is easier to view when looking at the history. If you neglect to do this, then you'll have to spend time and effort trying to understand what you did, as opposed to a quick high-level description.
• When you check files into VSS, it ensures that you aren't able to make changes without checking out, by setting your local copy of the file to read-only. It doesn't really make sense to override this, because the version stored in the repository is the current one, not your local copy.
• Bottom line...don't try and break the system. VSS tries to enable a framework for good development practices. Yes, it can be bypassed or overridden, but if you're serious enough about increasing the quality of your software, I would suggest following the framework...even if it is bit more work.