4. AccuRev Workspaces and
Reference Trees

As described in AccuRev’s Stream Hierarchy, AccuRev uses streams to organize your project data, as any number of projects can be under way concurrently. But streams are not the entire story. A stream is just a bookkeeping device, though a very sophisticated one! It’s a mechanism that records which versions of files are in use for a particular development task. The promote command propagates an existing version of a file from a lower-level stream to a higher-level stream.

But what about the actual files themselves, which developers edit and build software systems with? How are new versions of files created in the first place? In other words, how do users access AccuRev-controlled files, in order to perform their day-to-day development tasks? Through workspaces.

A workspace is a special type of stream — one that is associated with a particular user and a particular location on the file system. We’ve said that a depot’s files are organized into a directory tree; a workspace instantiates all or part of that directory tree at the specified location. Which parts are instantiated depend on what stream the workspace is “based on” (that is, what stream is the workspace’s parent). That stream is said to be the backing stream for the workspace; we’ll explain this term in Updating a Workspace.

For example, suppose a stream contains these versions of the elements in a depot:

src/gizmo.c version 45
src/frammis.c version 39
src/base.h verion 8
src/release_number.txt version 4
doc/Gizmo_Overview.doc version 19
doc/Gizmo_Relnotes.doc version 3

A workspace based on this stream is a directory tree containing:

•	a src subdirectory, containing four files (gizmo.c, frammis.c, base.h, release_number.txt).

•	a doc subdirectory, containing two files (Gizmo_Overview.doc, Gizmo_Relnotes.doc).

Another stream in the depot’s stream hierarchy might contain different versions of some or all the files. So, for example, the contents of files release_number.txt and Gizmo_Relnotes.doc might be different in a workspace based on another stream.

Any number of workspaces can be based on the same stream. A typical scenario is for all the members of a project team to maintain workspaces based on the stream that records the project’s ongoing work. Conversely, a workspace can be based on any stream. But typically, workspaces are created only at the “leaf level” of a depot’s tree-structured stream hierarchy: if a stream acts as the backing stream for one or more workspaces, it generally doesn’t have child streams, too.