The Workspace as a Stream

The diagram above, showing how data flows from a workspace into the repository, is an oversimplification. Changes that you make in your workspace don’t actually go directly into the backing stream. Long experience with configuration management systems has shown that users sometimes enter changes into the repository before they’re truly ready to be shared with others — for example, code that’s never been tested. But a delaying strategy also has its drawbacks — for example, it increases the chances of mistakenly deleting several weeks worth of changes without ever preserving them in the repository.

Some other version control systems use “private branches” to address these issues. AccuRev solved the problem by making each workspace a special type of stream. Here’s a more detailed diagram showing how data flows from a workspace into the repository:

This diagram shows that in AccuRev’s client-server world, a workspace has one foot on each side of the divide:

•

The instantiated directory tree associated with a workspace (the workspace tree) lives on the local file system. The files you work with on a day-to-day basis are entirely in the workspace tree.

•

The workspace (or workspace stream) lives in the data repository managed by the AccuRev Server. It contains all of the workspace’s configuration information. And it resides, as all streams do, entirely within the metadata stored for a particular depot.

The diagram also shows that recording a new version of a file in the backing stream is a two-step process:

The keep command creates a new version in the workspace stream. Think of keep as moving data from the client side to the server side. This command also copies the file in your workspace tree to the depot’s file storage area. That version is visible only to your workspace.

The promote command propagates the version from the workspace stream to the backing stream. This command operates totally within the metadata stored for the depot. No files are copied to the file storage area during a promote.

Why the extra stream and the extra step? Isn’t it redundant? No, because the workspace stream and backing stream play different roles. The whole idea of the workspace is to provide a degree of isolation from the changes that others are making concurrently. The workspace stream makes the isolation more flexible. It enables you to keep any number of intermediate versions of a file in your workspace, before “going public” by promote’ing the most recent version. If you decide that you’ve headed off in the wrong direction, you can revert a file to any of those intermediate versions. You can even purge all the work you’ve done on a file, which reverts to using the version in the backing stream.

All the intermediate versions that you keep are stored permanently in the depot, even the versions you never promote. Thus, the keep command provides a data-backup capability: “save a copy of this file, just in case I ever want to restore it to its current state”. It also means you can change your mind as many times as you like about which version of a file should be shared with the rest of the world.

Real Versions and Virtual Versions

The difference between keep and promote highlights an important aspect of the way that AccuRev organizes and manages development data. It also highlights the difference between backing streams and workspace streams.

All “real” development takes place in the workspace tree. The keep command preserves the changes you’ve made to a file. Accordingly, versions created by the keep command are called real versions. Every real version can only be created in the workspace stream.

By contrast, the promote command does not record a change to any file. Rather, it changes availability of a change that was previously recorded with keep. The version that promote creates in a higher-level stream is called a virtual version; each virtual version is just an alias for an existing real version in some workspace stream.

Active Files and the Default Group

The AccuRev repository keeps track of which files have changed in your workspace. This set of files is called the workspace’s default group. Many of the changes are new versions, created with keep. The default group also includes renamed or relocated files (move command), deleted files (defunct command), and added files (add command), etc.

When you promote a file’s changes from your workspace stream to the backing stream, the file is removed from the workspace’s default group. This reflects the fact that you’re done working on that file — at least for now! Similarly, a purge of your work on a file removes the file from the workspace’s default group.