A Tale of Two Trees


Our discussion of source control must begin by defining the basic terms and describing the basic operations. Let's start by defining two important terms: repository and working folder.

An SCM tool provides a place to store your source code. We call this place a repository. The repository exists on a server machine and is shared by everyone on your team.

Each individual developer does her work in a working folder, which is located on a desktop machine and accessed using a client.

Each of these things is basically a hierarchy of folders. A specific file in the repository is described by its path, just like we describe a specific file on the file system of your local machine. In Vault and SourceSafe, a repository path starts with a dollar sign. For example, the path for a file might look like this:


The workflow of a developer is an infinite loop which looks something like this:

  • Copy the contents of the repository into a working folder.
  • Make changes to the code in the working folder.
  • Update the repository to incorporate those changes.
  • Repeat.

I've omitted certain details like staff meetings and vacations, but this loop essentially describes the life of a developer who is working with an SCM tool. The repository is the official place where all completed work is stored. A task is not considered to be completed until the repository contains the result of that task.

Let's imagine for a moment what life would be like without this distinction between working folder and repository. In a single-person team, the situation could be described as tolerable. However, for any plurality of developers, things can get very messy.

I've seen people try it. They store their code on a file server. Everyone uses Windows file sharing and edits the source files in place. When somebody wants to edit main.cpp, they shout across the hall and ask if anybody else is using that file. Their Ethernet is saturated most of the time because the developers are actually compiling on their network drives. When we sell our source control tool to someone in this situation, I feel like an ER doctor. I go home that night with a feeling of true contentment, because I know that I have saved a life.

Best Practice: Don't Break the Tree

The benefit of working folders is mostly lost if the contents of the repository become "broken." At all times, the contents of the repository should be in a state which allows everyone on the team to continue to work. If a developer checks in some code which won't build or won't pass the test suite, the entire team grinds to a halt.

Many teams have some sort of a social penalty which is applied to developers who break the tree. I'm not talking about anything severe, just a little incentive to remind developers to be careful. For example, require the guilty party put a dollar in a glass jar. (Use the money to take the team to go see a movie after the product is shipped.) Another idea is to require the guilty developer to make the coffee every morning. The point is to make the developer feel embarrassed, but not punished. With an SCM tool, working on a multi-person team is much simpler. Each developer has a working folder which is a private workspace. He can make changes to his working folder without adversely affecting the rest of the team.

Terminology note: Not all SCM tools use the exact terms I am using here. Many systems use the word "directory" instead of "folder." Some SCM tools, including SourceSafe, use the word "database" instead of "repository." In the context of Vault, these two words have a different meaning. Vault allows multiple repositories to

About the author

AgileConnection is a TechWell community.

Through conferences, training, consulting, and online resources, TechWell helps you develop and deliver great software every day.