mkstream

create a new stream

Usage

accurev mkstream -s <stream> -b <backing-stream> [ -kp ] [ --gated ]
[ -t <time-spec> ]

Description

The mkstream command creates a new stream that is based on an existing stream called the backing stream. A stream and its backing stream are sometimes referred to as "child" and "parent" streams, respectively.

You can use the mkstream command to create dynamic, pass-through, and gated streams. Use the mksnap command to create snapshot streams. See Entity Names for information on naming streams.

Dynamic Streams

A dynamic stream is a stream whose content changes over time, with new versions promoted from child workspaces and/or from other dynamic streams. It also inherits versions from its parent stream. AccuRev creates streams as dynamic streams by default.

Pass-Through Streams

A pass-through stream is a special kind of dynamic stream, so called because a version that is promoted to such a stream automatically passes through to its parent stream. The file does not 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.

Gated Streams

A gated stream is a stream that you use to control whether changes promoted into it are automatically promoted out of it, often based on meeting externally established criteria (such as passing a test suite or completing a successful nightly build, for example). Gated streams combine attributes of both dynamic and pass-through streams, and they have features that are unique to them. For example, like dynamic streams, the content of a gated stream changes over time; and like pass-through streams, versions promoted to a gated stream pass through it to the gated stream’s parent. Unique to gated streams is a special type of stream called a staging stream.

You cannot set a basis time on a gated stream.

How Streams Change

A newly created stream contains the same set of element versions as its backing stream. (If you use the -t option when creating a dynamic stream, this is 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”.

Active Changes to a Stream

The promote command places a new version of one or more elements in a stream. This is termed an “active change”, because it is 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.

Promote behaves differently for pass-through and gated streams:

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.

When you promote from a workspace or child stream of a gated stream, those versions become active in a staging stream -- an intermediate stream that AccuRev creates automatically when you create or reparent a workspace or stream off it. Changes promoted to a gated stream remain in the staging stream’s default group until they satisfy the criteria established on the gated stream; once they do, those versions are promoted automatically through the gated stream directly to the gated stream’s backing (parent) stream.

A stream’s active elements do not experience any of the “passive” changes described in the next section.

Passive Changes to a Stream

Elements that are not currently active can still change, “passively”. Dynamic, pass-through, gated, and staging streams inherit changes automatically from their backing streams. If a new version of foo.c is promoted to a backing (parent) stream, this new version automatically appears in all of the child 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.

A child whose parent is snapshot that was defined with the same <time-spec>.

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.

Options

-s <stream>

(required) Specify a name for the new stream. The name may begin with a digit (provided there is at least one non-digit in the name), must not begin with a dot (.), must not include either a slash (/) or a backslash (\) and must not be a name of digits only.

-b <backing-stream>

Specify an existing stream, on which the new stream will be based.

-kp

Make the new stream a pass-through stream.

--gated

Make the new stream a gated 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, "2007/08/07 20:27:15", for example. Note that you must use quotes when specifying time-spec as YYYY/MM/DD HH:MM:SS to ensure that the entire argument is interpreted by the command shell as a single token.

Time keyword: now

Transaction number as a positive integer: e.g. 146 or 23965

Transaction number keyword: highest

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) determines how a timewarp will be handled. See also System Clock Synchronization in the AccuRev Admin 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

Create a gated stream called gizmo_gate backed by stream gizmo:

> accurev mkstream -s gizmo_gate -b gizmo --gated

See Also

chstream, lock, promote, remove, unlock