The Three Levels of Source Code Control Enlightenment

---

Most developers start out writing code without any sort of source code control, except perhaps for making occasional backups of an entire directory of stuff. But gradually, most of us realize that having a tool help keep track of code changes and prevent code loss is a good idea. We tend to go through three levels of enlightenment in this process, starting as beginning users and gradually developing expertise. In this section, I’ll review the three levels so that you can judge where you are in the process—and how much of the journey might remain.

Tip

I’ll be describing general source code control concepts and commands in this section, without reference to actual products. Not every product will implement all of these commands, and the actual operations may differ. For example, Concurrent Versions System (CVS) has no concept of checking out a file, while Visual SourceSafe (VSS) insists on it.

Level 1: Opening Your Eyes

The first level of enlightenment is simple: You start using source code control. For developers who are familiar with Microsoft tools, this normally takes the form of installing VSS, setting up a server, and putting a project into the VSS database. From there, you can get by with only six commands: Create Project, Add, Get, Check Out, Undo Check Out, and Check In:

• The Create Project command creates a new area in the source code control database (sometimes called a repository) to hold files. Projects can generally be nested.

• The Add command adds a file to the source code control database. When you use the Add command, you’re stating that it’s important to keep track of this file.

• The Get command is the reverse of the Add command; it gets the current version of a file from the source code control database and places it on your hard drive. If you already have a copy of the file, Get checks to see if there are any changes in the database, and if so, overwrites your local copy.

• The Check Out command says that you’re going to actively work on a particular file. Depending on your source code control system, this may prevent others from making changes to the file. Check Out normally performs an implicit Get to make sure you start with a current copy of the file.

• The Undo Check Out command says that you’ve decided you didn’t want to make any changes after all. It throws away any changes you’ve made and unlocks the file. This is the easiest way to get rid of changes that didn’t turn out to be a good idea after all.

• The Check In command says that you’re done making changes, and puts your current version of the file back into the source code control database. It also unlocks the file so that others may make changes.

Going from no source code control at all to this first level has two main benefits: code protection and code history.

When you have only a single copy of your source code, you’re risking everything to the vagaries of your hardware. What happens if your hard drive crashes and you haven’t backed up the code? Using a source code control server can help protect against this sort of catastrophic failure. Ideally, the source code control server is a separate computer from the client machine where you’re writing the code. But even if it’s on the same machine, you can store the source code control database on a separate hard drive. Doing so gives you automatic protection against single hardware failures (though it still won’t protect you against site-wide catastrophes like a fire; for important code, you should do periodic off-site backups as well).

Why is code history important? Imagine you’ve been working on an application for a while, and versions 1.0, 1.1, 1.2, 1.3, and 1.4 have all shipped to clients. Now a customer reports a bug in version 1.3. Is that same bug in earlier versions? Is it in later versions? If your computer only has the latest version of the source code for your application, you’ll never know the answer to those questions. A good source code control system will let you look at your application’s code as it existed at any point in time, so you can tell when a particular bug snuck into the code stream.

Source code control history can also help you keep track of the work that’s been done on any particular file. Most source code control systems let you add a comment whenever you add or check in a file. The summary of these comments can provide a pretty good look at who did what and when they did it, as shown in Figure 3.1.

Figure 3.1: Viewing a file’s history using SourceGear Vault

Level 2: The SCC Journeyman

The next step in your path to source code enlightenment is to be able to effectively manage your source code tree. Storing code in the source code control system is a good first step, but you’ll need to learn a few more tricks if you want to be able to use it effectively. In particular, you should know about the Label, Share, Branch, and Merge commands:

• The Label command assigns a friendly name to a specific version of a file or set of files so that you can find them again by name in the future.

• The Share command allows a single file to appear in more than one project, while maintaining only one copy in the source code control database.

• The Branch command lets development diverge, making copies of a file in two separate branches and letting them change independently.

• The Merge command takes changes from one branch and applies them to another branch.

Note

One typical use for the Label command is to apply a new label to the build tree every night so that you can easily recover the state of the project on any specified day. For more information, see Chapter 13, “Mastering the Build Process.”

When you master these commands, you’ll be prepared to manage fairly complex release scenarios. Sharing and labeling are fairly obvious, but you might not immediately see a use for branching and merging. One typical situation where these commands are useful is in preparing to release a product while simultaneously working on the next version. You don’t want bits of the version 2 feature set creeping into version 1, but you still need to fix bugs in version 1. In that case, you’d choose to create a Version1Release branch, as shown schematically in Figure 3.2. This lets one group of developers tidy up the last few bugs in version 1, while another group works on version 2 features.

Figure 3.2: Creating a branch for a release

In this diagram, development proceeds in a single group of version 1 files until the branch, marked with a B. After that,there are two separate sets of the same files, with differing contents. Most source code control systems identify one branch as the trunk; here I ’ve assigned that designation to the version 2 files

But what happens after the version 1 release? It’s quite possible that some of the bug fixes on the version 1 branch should also be made to the version 2 branch. Rather than retype those fixes yourself, you can use your source code control system’s Merge command. Merge takes changes from one branch and applies them to another branch, as shown schematically in Figure 3.3.

Figure 3.3: Merging changes from a branch back to the trunk

You might also find yourself creating a branch but never merging it back. For example, if you’re unsure whether a major refactoring of your code will leave things in a better state, start a branch to test it out. If the refactoring works, you can merge the changes back into the main line of development. If not, simply abandon the branch.

Level 3: Experts Only

Many users will be able to do all of their source code control work with just the 10 commands that I’ve discussed so far. But depending on your source code control system, lots of other commands may be available. Some of these are useful in specialized situations; others sometimes appear to exist just so a package can boast of more choices than the competition. Table 3.1 lists some of the commands that you might find in a source code control system.

Table 3.1: Advanced Source Code Control Features

Command	Description
Cloak	Hides a project in the repository so that it doesn’t appear when you’re working with files. There’s normally an Uncloak to reverse this.
Delete	Removes a file from the repository. Depending on the product, this may actually destroy all trace of the file, or simply hide it.
Move	Relocates a file or subproject to a new parent project.
Pin	Freezes a shared file at a particular version in a particular project. There’s normally an Unpin to reverse this.
Rename	Renames a file or project.
Rollback	Reverts a file to an earlier version, destroying all changes made after that version. Command Description

In addition, most source code control systems have some way to manage security. This may take the form of integration with Windows security, or there may be an entirely separate list of users and passwords that someone has to manage.

Whatever product you’re using, it’s worth spending a few hours to read the manual, so you know what advanced capabilities it has. Don’t try to use all of the commands immediately, however; start with the basic set. Then when you run into an unusual situation, you can consider whether there’s some product-specific way to handle the problem.

Note

Whatever your level of source code control expertise, you should recognize that in some cases source code control is overkill. For example, small bits of code for articles or training, or utility code that you’ll run only once and then throw away, probably don’t need to be in your source code control system.

---