Stream paths and inheritance

A stream specification defines the paths that the stream contains and the actions allowed on those paths.

A child stream might or might not inherit its view from its parent stream. When inheritance is enabled, a child stream implicitly inherits from its parent stream. Such a child stream inherits folder paths and behavioral rules from its parent.

Each path is a line in the stream definition. A path contains one or more folders or files. A folder is a path with a wildcard, such as ...

Paths	Behavioral Rules
A child normally inherits paths from its parent. However, in the case of a release stream, it might be preferable to not inherit from the parent stream. It is common to filter some files from the parent by excluding them. In this case, the child has fewer paths than the parent. The use of import by a child stream allows the child stream to import files from anywhere in the depot. In this case, the child has more paths than the parent.	Path types can be inherited from parent streams. When they are inherited, you cannot override the effects of the path types assigned by parent streams. 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.

Paths

Behavioral Rules

A child normally inherits paths from its parent. However, in the case of a release stream, it might be preferable to not inherit from the parent stream.

It is common to filter some files from the parent by excluding them. In this case, the child has fewer paths than the parent.

The use of import by a child stream allows the child stream to import files from anywhere in the depot. In this case, the child has more paths than the parent.

Path types can be inherited from parent streams. When they are inherited, you cannot override the effects of the path types assigned by parent streams.

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.

A child stream that inherits its view from its parent cannot add an isolate path unless the folders in that path are also included in the parent. The following Dev stream can isolate the config/ folder because that folder is included as a share or isolate path in Main:

Example Simple share

Two streams, //Ace/main and its child //Ace/dev.

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

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

The entire stream path is shared. When you switch your workspace to the //Ace/main stream, the workspace view is:

//Ace/main/... //bruno_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:

//Ace/dev/... //bruno_ws/...

The branch view for //Ace/dev/ is:

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

The entire dev stream can be synced to workspaces, and the entire stream can be branched, merged, and copied.

Example Share and import

In this example, software modules are housed in three separate depots: //Acme, //Red, and //Tango.

The Acme mainline is:

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, the workspace view is:

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

The stream’s Paths field lists folders relative to the root of the stream. Those are the folders you 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.

Example Share, isolate, exclude, and import

Suppose your team doesn’t want to do development in the mainline. In this example, the XProd feature team has its own development stream:

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

When you switch your workspace to the //Acme/XProd stream, the view is:

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

Because of workspace view inheritance:

the contents of imported paths are mapped into your workspace
the shared and isolated paths are mapped to the child stream. These contain the files the XProd team is working on and will be submitting changes to.
the excluded path (marked with a minus sign in the view) doesn’t appear in the workspace.

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.

-//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 might appear that you’re working in a full branch of //Acme/Main, but the actual branch is quite small.

Example Child that shares all of the above parent

Lisa creates a child stream from //Acme/XProd. Her stream spec is:

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

Lisa’s stream has the default view paths. Given that Lisa’s entire stream path is set to share, you might expect that her entire workspace will be mapped to her stream. This is not the case because inherited behaviors take precedence. Sharing applies only to paths that are shared in the parent as well. A workspace for Lisa’s stream, with its default view path, has this client view:

//Acme/Main/apps/...        //bruno_ws/apps/...
-//Acme/LisaDev/tests/...   //bruno_ws/tests/...
//Acme/LisaDev/apps/bin/... //bruno_ws/apps/bin/...
//Acme/LisaDev/apps/xp/...  //bruno_ws/apps/xp/...
//Red/R6.1/stuff/...        //bruno_ws/stuff/...
//Tango/tools/...           //bruno_ws/tools/...

A workspace in Lisa’s stream is the same as a workspace in the XProd stream, with one exception: the paths available for submit are rooted in //Acme/LisaDev. If you work in Lisa’s stream, you expect to submit changes to her stream.

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

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

The default path allows Lisa to:

branch her own versions of the paths her team is working on
have a workspace with the identical view of non-branched files that she would have in the parent stream