Stream view configuration

To configure the files that a stream contains, you define the stream view (Stream dialog > Advanced tab > Views). The Views area contains Paths, Remapped, and Ignored. These three together are what a child stream inherits if it has Parent View: inherit.

The stream view controls stream behavior. Helix Server uses stream views to generate workspace viewsClosed A set of mappings that specifies the correspondence between file locations in the depot and the client workspace. Each row in the workspace view consists of a pair of filespecs, first a depot filespec, then white space, and finally a filespec that shows a workspace location relative to the workspace root. and branch viewsClosed A specification of the branching relationship (branch mapping) between two codelines in the depot. Each branch view has a unique name and defines how files are mapped from the originating codeline to the target codeline. for you.

 

 

Mainline, development, and release streams are only visible in the Depot tree pane if the stream is populated.

A task stream is only visible in the Depot tree pane if that task stream is populated, has a workspace, and that workspace is the selected workspace.

Stream path types

Stream views use the following path types:

  • share: Files in shared paths can be synced (retrieved), submitted, and integrated (branched, merged, and copied). Shared paths are used for files whose changes will flow to and from other streams.
  • isolate: Files can be edited but the resulting changes cannot be integrated to other streams. Isolated paths are useful for storing nightly builds and other generated files, like bin directories.
  • import: Files are sourced from a specified location, and can be synced but cannot be submitted or integrated. Use imported paths for third-party libraries, which are required for building but are never edited. An imported path inherits its view from the parent stream unless its depot location is defined explicitly. Icons of imported files and folders are decorated with a halo in the parent stream from which they are imported.
  • import+: Functions like an import path in that it can reference an explicitly defined depot path, but unlike a standard import path, you can submit changes to the files in an import+ path.
  • exclude: Prevents files that would be inherited from the parent files from becoming part of the stream. Files in excluded paths cannot be synced, submitted, or integrated.

The following table shows the behavior of each path type at a glance:

Path type Merge/Copy Branch Sync Submit
share Y Y Y Y
isolate N N Y Y
import N N Y N
import+ N N Y Y
exclude N N N N

Stream path syntax

The syntax for specifying stream paths is similar to depot path syntax, with the leading //depot name and stream name removed. For example:

Depot path: //Ace/main/qa/...

Stream view path: qa/...

If you want your stream to be able to merge, copy, branch, and submit edits to qa, include a share path like this in the stream view:

share qa/...

Restrictions

Stream views are generated from the stream spec and do not allow:

  • Positional specifiers, such as %%1, which are supported in non-stream user-defined views as shown at Rearrange parts of filenames in Helix Core Command-Line (P4) Guide.

  • Overlay mapping (+), except for Sparse streams, which always have an overlay mapping.

  • Leading wildcards, such as ...txt

    However, share * in the Paths: field of the stream spec is allowed as a wildcard for the current directory, and share ... is allowed as a wildcard for the current directory and its subdirectories.

Tip

To search for a specific string in the stream spec, click inside the Paths: field and then press Ctrl+F. This opens the Find dialog.

Inheritance between parents and children

Child streams inherit folder paths and behavioral rules from their parents. When we talk about inheritance between parents and children, it helps to think in the following terms:

  • Permissiveness: what actions (submit, sync, etc) are permitted on a path?

    Path types are inherited from parent streams, and you cannot override the effects of the path types assigned by parent streams. In other words, child streams are always as permissive or less permissive than their parents, but never more permissive. For example, if a parent stream defines a path as isolate, its child streams cannot redefine the path as share to enable integrations.

  • Inclusiveness: what paths are included in the stream?

    Children cannot be more inclusive than their parents. Therefore, you cannot include a folder path in a child that is not also included its parent. For example, you cannot add an isolate path to a child if the folders in that path are not also included in the parent. In the following, the incorrectly defined Dev stream, which is a child of Main, contains an isolate path that will not work, because it includes folders that are not included in the parent. To isolate the config/ folder in the Dev stream, that folder has to be included as a share or isolate path in Main:

    Correct

    Incorrect

    Stream: //Acme/Main
    Parent: none
    Paths:	share apps/...
    	share tests/...
    	share config/...
    
    Stream: //Acme/Dev
    Parent: //Acme/Main
    Paths:	share apps/...
    	share tests/...
    	isolate config/...
    Stream: //Acme/Main
    Parent: none
    Paths:	share apps/...
    	share tests/...
    	
    
    Stream: //Acme/Dev
    Parent: //Acme/Main
    Paths:	share apps/...
    	share tests/...
    	isolate config/...

Examples

This section includes simple and more complex examples of stream usage.

Simple share

Let's start with a simple case: two streams, //Ace/main and its child, //Ace/dev.

Stream:	//Ace/main
Parent: none
Paths:	share ...
Stream: //Ace/dev
Parent: //Ace/main
Paths:  share ...

In this case, the entire stream path is shared. When you switch your workspace to the //Ace/main stream, the workspace view looks like this:

//Ace/main/... //your_ws/...

The workspace view maps the root of the //Ace/main stream to your workspace. When you switch your workspace to the //Ace/dev stream, the workspace view is this:

//Ace/dev/... //your_ws/...

And the branch view for //Ace/dev/ looks like this:

//Ace/dev/... //Ace/main/...

In other words, the entire dev stream can be synced to workspaces, and the entire stream can be branched, merged, and copied.

Share and import

Let's look at an example where software components are housed in three separate depots, //Acme, //Red, and //Tango.

The Acme mainline is configured like this:

>Stream:	//Acme/Main
Parent: none
Paths:	share apps/...
	share tests/...
	import stuff/... //Red/R6.1/stuff/...
 	import tools/... //Tango/tools/...

If you switch your workspace to the //Acme/Main stream, this would be your workspace view:

//Acme/Main/apps/... //your_ws/apps/...
//Acme/Main/tests/... //your_ws/tests/...
//Red/R6.1/stuff/... //your_ws/stuff/...
//Tango/tools/... //your_ws/tools/...

The stream's Paths field lists folders relative to the root of the stream. Those are the folders you will get in your workspace, beneath your workspace root. The shared folders are mapped to the //Acme/Main path, and the imported paths are mapped to their locations in the //Red and //Tango depots.

Share, isolate, exclude, and import

Let's say that your team doesn't want to do actual development in the mainline. In this example, the XProd feature team has a development stream of their own, defined like this:

>Stream: //Acme/XProd
Parent: //Acme/Main
Paths:	import ...
 	isolate apps/bin/...
	share apps/xp/...
	exclude tests/...

Switching your workspace to the //Acme/XProd stream gives you this view:

//Acme/Main/apps/... //your_ws/apps/...
//Acme/XProd/apps/bin/... //your_ws/apps/bin/...
//Acme/XProd/apps/xp/... //your_ws/apps/xp/...
//Red/R6.1/stuff/... //your_ws/stuff/...
//Tango/tools/... //your_ws/tools/...
-//Acme/XProd/tests/... //your_ws/tests/...

Here we see stream view inheritance at work. Imported paths are mapped to whatever they're mapped to in the parent's client view. The shared and isolated paths are mapped to the child stream; these contain the files the XProd team are working on and will be submitting changes to. And the excluded path (marked with a minus sign in the view) doesn't appear in the workspace at all.

Because the //Acme/XProd stream has a parent, it has a branch mapping that can be used by the copy and merge commands. That branch view consists of the following, with only one path shared by the child and parent. To view stream branch views, use P4, the Command Line Client:

>-//Acme/XProd/apps/... //Acme/Main/apps/...
-//Acme/XProd/apps/bin/... //Acme/Main/apps/bin/...
//Acme/XProd/apps/xp/... //Acme/Main/apps/xp/...
-//Acme/XProd/stuff/... //Acme/Main/stuff/...
-//Acme/XProd/tests/... //Acme/Main/tests/...
-//Acme/XProd/tools/... //Acme/Main/tools/...

When you work in an //Acme/XProd workspace, it feels as if you're working in a full branch of //Acme/Main, but the actual branch is quite small.

Child that shares all of the above parent

Let's suppose that Bob creates a child stream from //Acme/XProd. His stream spec looks like this:

Stream: //Acme/BobDev
Parent: //Acme/XProd
Paths: share ...

Bob's stream has the default view template. Given that Bob's entire stream path is set to "share," you might expect that his entire workspace is mapped to his stream. This is not the case because sharing applies only to paths that are shared in the parent. A workspace for Bob's stream, with its default view template, has this client view:

//Acme/Main/apps/... //your_ws/apps/...
-//Acme/BobDev/tests/... //your_ws/tests/...
//Acme/BobDev/apps/bin/... //your_ws/apps/bin/...
//Acme/BobDev/apps/xp/... //your_ws/apps/xp/...
//Red/R6.1/stuff/... //your_ws/stuff/...
//Tango/tools/... //your_ws/tools/...

A workspace in Bob's stream is the same as a workspace in the XProd stream with one exception: the paths available for submit are rooted in //Acme/BobDev. If you work in Bob's stream, you expect to submit changes to his stream.

By contrast, the branch view that maps the //Acme/BobDev stream to its parent maps only the path that is designated as shared in both streams:

-//Acme/Main/apps/... //XProd/apps/...
-//Acme/BobDev/tests/... //XProd/tests/...
-//Acme/BobDev/apps/bin/... //XProd/apps/bin/...
//Acme/BobDev/apps/xp/... //your_ws/apps/xp/...
-//Red/R6.1/stuff/... //XProd/stuff/...
-//Tango/tools/... //XProd/tools/...

The default template allows Bob to branch his own versions of the paths his team is working on, and have a workspace with the identical view of nonbranched files that he would have in the parent stream.

Remap files

Files can be remapped, which enables you to place them in a workspace location that differs from their depot location. For example, the following view specifies that the parent's docs files reside beneath the doctools path in workspaces defined for this stream.

Remapped:

Remapped:
docs/... doctools/docs/...

Ignore files

You can specify a list of file or directory names to be ignored in workspace views, which is useful for ensuring that artifacts such as object files or other interim files are never checked in or integrated. These types are excluded by the workspace view of workspaces associated with the stream. For example:

Ignored:
/tmp # ignores files named "tmp"
/tmp/... # ignores directories named tmp
.tmp # itnores file names ending in .tmp