How the Data Structures Get Their Data

Each of the data structures introduced above — backing stream, workspace stream, and workspace tree — is different in the way it gets changes (i.e. new data) from other parts of the development environment.

Backing Stream

The backing stream is, in most cases, a dynamic stream. (It can also be a snapshot or a time-based stream.) A dynamic stream is a changing configuration of its depot. At any given moment, it (logically) contains a simple table that indicates particular versions of a set of elements. For example:

 

Element	Version-ID
doc	garnet_dvt\1
doc\chap01.doc	garnet_dvt\5
doc\chap02.doc	garnet\3
doc\chap03.doc	garnet_dvt\2
src	garnet\1
src\garnet.c	garnet_dvt\12
src\commands.c	garnet_dvt\7
tools	garnet\3
tools\start.sh	garnet_dvt\6
tools\end.sh	garnet\2

At any given moment, a dynamic stream’s versions fall into two categories:

•	passive versions: versions that the stream inherits from its parent stream. Inheritance is automatic and instantaneous: as soon as a new version enters the parent stream, it is inherited at once by the child stream.

•	active versions: versions that have been Promoted to the stream, (usually) from lower-level workspaces and substreams. This set of versions constitutes the stream’s default group.

In the configuration table above, all the garnet_dvt\... version-IDs indicate active versions in the garnet_dvt stream. All the garnet\... version-IDs indicate passive versions, inherited from the parent stream, named garnet.

Workspace Stream

The workspace stream is the “behind the scenes” part of your workspace. It is the information contained in the database about changes made to your workspace. In many ways, it resembles a dynamic stream:

•	It’s a changing configuration of one of the repository’s depots.

•	It logically contains a particular version of some or all of the depot’s elements.

•	It doesn’t contain actual files, but is logically just a table of elements and version-IDs.

Note: When creating a new version of a file, the Keep command copies the file to the repository’s file-storage area, not to the workspace stream itself. The workspace stream just gets a version-ID for the new version; the version-ID serves as a pointer to the file in the file-storage area.

•	It contains active versions, created by explicit user commands: Add, Keep, Rename, Defunct, etc. The new versions in the repository preserve the changes that you’ve made to files in your workspace tree. (There’s only one way to create an active version in a dynamic stream: the Promote command.)

•	It also contains passive versions, inherited from its parent stream, the workspace’s backing stream.

The last item is where the crucial difference between workspace streams and dynamic streams comes into play. The versions inherited by the workspace stream are not the ones currently in the backing stream, but the versions that were in the backing stream when the workspace was last updated. This is called the workspace’s update level. More precisely, AccuRev records the number of the depot’s most recent transaction — say, transaction #32155 — as the workspace stream’s update level. So we can rephrase the principle:

The workspace stream inherits from the backing stream versions that were created in transactions up to and including the workspace’s update level.

Note: The update level of a workspace stream is very much like the optional basis time of a dynamic stream. Both mechanisms restrict the flow of versions to a child stream from its parent stream, based on a point in the depot’s development history.

Thus, a workspace stream is not updated dynamically when changes occur to its parent stream. It gets new versions from the backing stream only when you issue an Update command. This is how AccuRev implements the workspace’s user-controlled “privateness”, isolating it from the changes regularly being recorded in the backing stream by other team members.

To summarize: at any given moment, a workspace stream contains:

•	a set of passive, inherited versions, created in transactions that do not exceed the workspace’s update level. (A file that you’ve Promote’d since the last update is an exception. The version is passive, but was created after the workspace’s update.)

•	a set of active versions, which you’ve created in that workspace with such AccuRev user commands as Add, Keep, Rename, and Defunct.

Roughly speaking, the set of versions in the workspace stream indicates what data currently should be in your workspace tree. Examples:

•	The workspace stream contains active version garnet_dvt_mfj\9 of file commands.c, which you created with the Keep command. This means your workspace tree should contain a file commands.c that matches the repository file referenced by version-ID garnet_dvt_mfj\9.

•	The workspace stream contains passive version garnet_dvt\6 of file start.sh. This means your workspace tree should contain a file start.sh that matches the repository file referenced by the version in the backing stream, garnet_dvt\6.

If you modify a file without Keep’ing it (or modify it again after Keep’ing it), the file in the workspace tree does not exactly match the version in the workspace stream. AccuRev indicates this by reporting the file’s status as (modified).

Workspace Tree

The workspace tree is an ordinary directory tree, located in your personal disk storage. You can modify the contents of the workspace tree in two basic ways:

•	By invoking operating system commands, text-editing tools, IDEs, etc.

•

By invoking AccuRev commands to copy existing versions from the repository to the workspace tree. This can either overwrite existing files in the workspace tree or add new files. Both the Populate and Update commands copy versions from the workspace stream to the workspace tree. (So do a couple of other commands, such as Send to Workspace.)