About Streams

Perforce streams are "branches with brains," a containerized approach to managing bodies of related files such as codelines. Streams associate these bodies of related files with rules that define how you can work with those files, including how you can move changes between them. Most notably, streams are defined hierarchically using the mainline model, and Perforce generates the views for workspaces that are associated with a stream based on strictly inherited rules. Among the advantages of this approach are (1) change is propagated in a controlled way through the hierarchy that you define, and (2) you can compose the contents of a stream by defining its view, thereby providing all users who work in the stream with a consistent view of its contents.

The mainline model

The mainline model of software configuration management defines a structure based on the stability of the contents of the stream, from softest (unstable or experimental) to firmest (high-quality, releasable). Typically, the mainline is required to be fairly stable (for example, code must build), development codelines less stable, and release codelines the most stable.

Stream types

Perforce codifies the soft-to-firm model of stability in its standard stream types:

There are two additional stream types with special characteristics:

Stream hierarchy in the Stream Graph

In the P4V Streams tab, the Stream graph displays soft streams below the mainline and firm streams above it. For example, the following diagram shows a typical software development structure, consisting of a stable mainline, with experimental streams below it and release-quality streams above:


Basic stream structure for software development

In the stream graph, the most stable streams are always at the top and the least stable at the bottom. The stream graph also displays the parent-child relationships that control the propagation of change between codelines. All streams are children of the mainline, and all children can be parents of yet more children of the same type, enabling specific development and release codelines while ensuring that changes are propagated properly between codelines. The stream graph represents those paths of change propagation using arrow connectors.

For more information, see Using the Stream Graph.

Stream views

A stream is defined not just by its type, but also by its view, which specifies the files and folders that the stream contains and whether they can be edited, merged down, copied up, or branched to a new stream. Stream views define the files that you can work on in your workspace and what you can do with them. They also restrict the files that a child stream inherits from its parent. For example, let's say you have a mainline stream that includes the following directories of files:

//Acme/Main
--apps
--api
--resources
--docs

You want to branch to a development stream. You only need to work in the apps folder, but you need resources from the api and resources folders. You can create a development stream as a child of Main that includes the files in the apps folder, excludes the files in the docs folder, and imports the contents of the api and resources folders so you can use them but cannot edit and submit any changes to the depot. You assign a stream view to the child stream that enacts these rules. Perforce generates the workspaces -- and enforces the submit and integration rules -- from the stream view. Any children branched from this new stream inherit those rules. You can assign a more restrictive stream view to subsequent children, but you cannot assign a less restrictive one. Child streams cannot branch more than their parent streams are willing to share.

For more information, see About Stream Views.

Propagating change between streams

The primary principle of change propagation is merge down, copy up. The goal is to keep less stable streams up to date with their more stable parent or child, so that when change is propagated from a less stable stream to a more stable one, no work is overwritten. This approach keeps the resolve operation as simple as possible. Perforce's merge/copy and resolve features are the means by which you propagate change between streams. When you use streams, all changes are propagated between parent and child streams. If you want to merge or copy between peer streams (for example, to merge another developer's changes to your development stream), you must first reparent your stream (that is, edit the stream specification and change the Parent field). This approach is a key benefit of streams: the ability to configure the flow of change.

For more information, see Merging Down and Copying Up Between Streams.

Stream depots

Streams are stored in a stream depot, which is displayed in P4V like this: Streams depot. You cannot add a stream to a "classic" Perforce depot. You can add streams depots through P4Admin or the Perforce command-line client.

For more information, see Structuring Streams.

Terminology differences between command line client and P4V

P4V Term Command Line Term Description
Stream Root Stream The top level under the depot where files in the stream are stored
Stream Name A descriptive name that you assign and which is displayed to label the streams in the Stream Graph