The mkstream command creates a new
dynamic stream, based on an existing stream (termed the
backing stream). A stream and its backing stream are sometimes described as “child” and “parent” streams. See
Entity Names on page 6 for information on naming streams.
Unlike a snapshot, a dynamic stream changes over time. Elements can be added to the stream, deleted, or moved to different pathnames. New versions of the elements can be created in the stream.
A newly created dynamic stream contains the same set of element versions as its backing stream. (With
-t, it’s the set of versions that the backing stream contained at a particular point in time.) Thereafter, the dynamic stream’s contents can change, either “actively” or “passively”.
The promote command places a new version of one or more elements in a dynamic stream. This is termed an “active change”, because it’s the result of an explicit command (
promote), and is recorded in the database as a transaction.
Promoting versions of elements into a stream makes those elements “active” in the stream. (A stream’s
default group is its set of “active” elements.) Those elements remain active in the stream until the versions are
promoted out of the stream, or are
purged from the stream.
Note: if you promote versions to a pass-through stream, the versions are actually (and automatically) promoted to the stream’s parent. A pass-through stream cannot have any active elements; its default group is always empty.
In a dynamic stream, elements that are not currently active can still change, “passively”. A dynamic stream inherits changes automatically from its backing stream. If a new version of
foo.c is promoted to a backing (“parent”) stream, this new version automatically appears in all of the “child” dynamic streams where
foo.c is not currently active.
Such changes are termed “passive”, because they are implicit and automatic. They are not recorded as separate transactions. Passive changes can only occur to a stream whose parent is, itself, changeable. If the parent is a snapshot, the child won’t experience any passive changes.
In effect, the -t option “takes a snapshot” of the parent stream at a particular time, called the
basis time. But the following are only similar, not quite identical:
•
|
In a child created with mkstream -t, you can promote versions to the parent (because the parent is a dynamic stream). The elements remain active in the child stream.
|
•
|
In a child of a snapshot, you cannot promote changes to the parent (because the parent is a snapshot, and thus immutable). You can propagate the changes to other dynamic streams using promote -s -S or the GUI’s Change Palette. This operation leaves the changed files active in the child stream.
|
You may wish to avoid the complications described above by not using mkstream -t to create streams for active development. Instead, you can use
mkstream -t to create “changeable snapshot” streams:
•
|
Create a child stream using mkstream -t <time-1>, and prevent changes to the stream using lock. This is similar to creating a snapshot of the parent stream at <time-1>.
|
A pass-through stream is a special kind of dynamic stream. A version that is promoted to such a stream automatically passes through to its parent stream. The file doesn’t become active in the pass-through stream (that is, the pass-through stream has no default group); it
does become active in the parent of the pass-through stream.
•
|
Time in <YYYY/MM/DD HH:MM:SS> format: e.g. 2001/08/07 20:27:15. Note that you might need to use quotes in composing the argument following -t; the entire argument must be interpreted by the command shell as a single token.
|
Create a stream based on gizmo at the present time:
Create a changeable snapshot of the gizmo stream at May 2nd, 2000 at 2:55pm: