AccuRev® Command-Line Reference : mkstream

mkstream
create a new dynamic stream
Usage
accurev mkstream -s <stream> -b <backing-stream> [ -kp ] [ -t <time-spec> ]
Description
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”.
Note: as of AccuRev 4.7.2, the data stored in the database by the mkstream command includes the stream-ID. Streams and workspaces created prior to installing 4.7.2 will not display this additional stream information as part of the hist command.
Active Changes to a Dynamic Stream
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.
A stream’s active elements do not experience any of the “passive” changes described in the next section.
Passive Changes to a Dynamic Stream
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.
Using the -t Option
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:
A child, created with -t <time-spec>, with a dynamic stream as its parent.
Both child streams initially get the same set of versions. And both child streams can keep new versions of elements. The difference is in promoting the new versions:
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 other situations, elements become inactive in the child stream after a promotion. Such elements revert to “passively” using the parent stream’s version. In this situation, becoming inactive would make the elements revert to the version that existed at the time specified with mkstream -t. This “surprise” is avoided by having the elements remain active.)
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>.
Subsequently, after changes have been made in the parent stream, unlock the child stream, update its “snapshot” with chstream -t <time-2>, then lock it again.
Pass-Through Streams
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.
Pass-through streams are useful for grouping lower-level streams and/or workspaces. This makes it possible to reparent all the streams in the group in a single operation.
You cannot set a basis time on a pass-through stream.
Options
-s <stream>
(required) Specify a name for the new stream. The name must begin with a non-digit other than dot (.), and must not include either a slash (/) or a backslash (\).
-b <backing-stream>
Specify an existing stream, on which the new stream will be based.
-kp
Make the new stream a pass-through stream.
-t <time-spec>
Bases the new stream on the state of the backing stream at the specified basis time. A time-spec can be any of the following:
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.
You cannot specify a time that is before the creation of the backing stream, or after the current time. You cannot set a basis time on a pass-through stream.
See Using the -t Option above.
When using the –t option, take into account the possibility of a timewarp. The AC_SYNC environment variable (see AccuRev User Preferences on page 6) determines how a timewarp will be handled. See also section System Clock Synchronization on page 31 of the AccuRev Administrator’s Guide.
Examples
Create a dynamic stream backed by another dynamic stream:
> accurev mkstream -s gizmo_maint -b gizmo
Create a stream based on gizmo at the present time:
> accurev mkstream -s gizmo_fixes -b gizmo -t now
Create a changeable snapshot of the gizmo stream at May 2nd, 2000 at 2:55pm:
> accurev mkstream -s gizmo_s1 -b gizmo -t "2000/05/02 14:55:00"
> accurev lock gizmo_s1
See Also
chstream, lock, mkstream, promote, unlock

AccuRev, Inc.
Phone: 781-861-8700
Fax: 781-861-8704
support@accurev.com