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:

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

apps 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 apps 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:

  1. In the Stream editor, you select a stream type of Virtual.
  2. In the Paths field, you enter stream paths that exclude all but the p4admin folder:

    exclude ...
    share p4-qt/apps/p4admin/...

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

//depot/development/p4-qt/apps/p4admin/... p4-qt/apps/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:

virtual streams in Streams graph

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 graph after submitting change through virtual stream

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:

For more information about stream paths, see About Stream Views.

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).

  1. In the Stream Graph, context-click a stream and select Create New Stream from '<stream name>'...
  2. 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.
  3. On the Advanced tab in the Stream dialog, enter the stream paths that define the scope of the virtual stream.
  4. Complete the stream settings just as you would any other stream.
  5. 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.