Working with virtual streams

Virtual streams provide users with the ability to restrict the workspace view of a real stream. Virtual streams act as a filter. They are useful when you want to:

Submit changes directly to a stream but do not want to sync all of the files in the stream view to your workspace.
Develop against the same stream but switch imported libraries, such as when you develop across multiple platforms.

For example, let’s say you are working in a development stream whose view includes all of the files in the help directory:

If you want to work only on the contents of the p4admin folder, you might not want the burden of syncing all of the files in the help directory to your workspace. You cannot change the workspace view of the development stream to exclude the folders you do not want; the workspace view is inherent to the stream. You could create a child of the development stream that excludes the files you do not want, but then you would be unable to submit your changes directly to the development stream; you would be subject to an unnecessary merge-down/copy-up routine every time you submit. Instead, you create a virtual stream as a child of the development stream that excludes all but the p4admin folder:

In the Stream editor, you select a stream type of Virtual.
In the Paths field, you enter stream paths that exclude all but the p4admin folder:
```
exclude ...
share doc/help/p4admin/...
```

This gives you a virtual stream with the workspace view you want:

//P4V/doc-dev/doc/help/p4admin/... doc/help/p4admin/...

When you submit changes to the virtual stream, those changes are submitted directly to its parent development stream.

View virtual streams

In the Streams Graph, a virtual stream is represented with a dashed border, and its relationship with its base parent stream is represented by a gray line without merge or copy indicators. Virtual children of the mainline are displayed next to the mainline. All other virtual streams are displayed above or below their base parents, depending on whether their parents are development or release streams:

The streams graph shows no merge or copy indicators for virtual streams. Rather, the base parent of a virtual stream carries the merge and copy indicators, because the actual merges and copies flow between real streams. When you submit a change through a virtual stream, the copy up or merge down arrows appear between the virtual stream’s base parent and the real streams that should be merged down or copied up to. For example, if you submit a change to main through the admin-auth virtual stream, merge arrows appear between the main stream and its real children:

Stream path behavior in virtual streams

You use stream paths to define a virtual stream just as you do when you define a real stream. However, the path types can behave differently. In particular, isolate and import can behave like share in the context of virtual streams and may therefore be redundant when you define your virtual stream view:

Share: in real streams, files included in share paths can be merged, copied, branched, synced (retrieved) and submitted to the depot. In virtual streams, files included in share paths cannot be submitted, merged, copied, or branched, since, by definition, virtual streams do not allow those actions (submitting, branching, merging, and copying actually happen through the virtual stream’s real parent).
Isolate: in real streams, files included in isolate paths can be synced to your workspace and submitted to the depot, but not branched, merged, or copied. In virtual streams, isolate functions essentially like share, since virtual streams do not, by definition, allow submits, branches, merges, or copies. This does not mean that there is no reason to use isolate when creating a virtual stream, however; if you intend to create a real child from the virtual stream, the files in the isolate path in the real child stream will behave according to expected isolate behavior.
Import: in real streams, files included in import paths can be synced but not merged, copied, branched, or submitted. In virtual streams, import behaves like share if your import paths are importing from the real parent. However, if you import an explicit depot path from another location, then typical import behavior occurs.

For example, let’s say your parent stream, //Acme/Main, includes the following file directory:
```
//Acme/Main/lib
```
When you define a virtual stream as a child of //Acme/Main, the following import path is redundant, since it behaves just like a share:
```
share ...
     import lib/...
```
The import path is superfluous, unless you intend to create real children from the virtual stream. However, if you want to import libraries from an explicit depot location to your virtual stream, your import path is necessary and functions just as it would for a real stream.
```
share ...
     import lib/... //Red/R6.1/stuff/...
```
Exclude: always behaves just as it does in real streams.

For more information about stream paths, see the section "Stream path" in the "Streams" chapter of the Helix Core Command-Line (P4) Guide.

Create a virtual stream

You can create a virtual stream as a child of any stream type — main, development, release, or another virtual stream. The virtual stream takes the behavior of its parent stream type (that is, a virtual stream created as a child of a main stream acts like a main stream, and a virtual stream created as a child of a development stream acts like a development stream).

In the Stream Graph, right-click a stream and select Create New Stream from '<stream name>'….
On the Basic Settings tab in the Stream dialog, select a Stream type of virtual - used to narrow the scope and submit directly to the parent..
On the Advanced tab in the Stream dialog, enter the stream paths that define the scope of the virtual stream.
Complete the stream settings just as you would any other stream.
Click OK.

Note

Just as you can create a virtual stream as the child of any stream type, you can also create a real stream as the child of a virtual stream.

For more information about using the Stream dialog to create or edit streams, see Creating Streams.

Submit changes to a virtual stream

You submit changes to a virtual stream just as you would to a real stream, however the changes are actually submitted to the virtual stream’s base parent.

Merge and copy to a virtual stream

You merge changes down or copy changes up to a virtual stream just as you would to a real stream, however the merge or copy is actually submitted to the virtual stream’s base parent. You might find it more straightforward to copy and merge directly between real streams.