Working with task streams

Task streams are lightweight branches that you can use for work that affects a small portion of a full project branch. Task streams enable you to work privately, switch contexts quickly, and reduce the amount of metadata managed by Helix Server. They are ideal for developing small-to-medium features and bug fixes.

Overview

Task streams are sparse and semi-private:

When you first create a task stream, only the workspaces associated with that task stream can see the files in the stream or use Diff against those files.
When you submit changes to the task stream, the changed files are visible to users who are not using the task stream, but that is all they can see.

The workspaces associated with the task stream remain the only ones that can see all files and activity (such as checkouts and shelves).

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.

The typical task stream workflow usually ends with the task stream being deleted or unloaded:

Create a task stream from a parent stream (although a parent is not required).
Populate the task stream.
Work on a new feature and submit the code.
Merge down changes from the parent stream to the task stream.
Copy your changes up.
Delete or unload the task stream.

You do not always have to delete or unload the task stream. For example, if you find yourself editing more than half the files in your task stream, that stream will no longer provide any savings in server overhead or metadata management activity. It can make sense then to convert your task stream into a regular stream.

Using a task stream feels just like using a regular stream, with the following exceptions:

Task streams do not require a parent stream.

This enables users who are not working in a stream depot to create task streams. The task stream must reside in a stream depot, but that depot can be no more than a holding place for your task stream. Contact your Helix Server administrator or project lead for information about the stream depot to use. For more information, see Create a task stream without a parent.
The parent can reside in another depot.

Task streams can quickly accumulate in a depot until they are deleted or unloaded. To keep a project depot uncluttered by task streams, your Helix Server administrator or project lead may choose to establish certain streams depots as dedicated holding places for task streams. In that case, you create your stream in the task streams depot as a child of a parent in the project depot. Even though the task stream resides in another depot, you can see it displayed in the Stream Graph view of the parent’s depot. For more information, see Create a task stream in a different depot.
Task streams cannot have child streams.
Task streams cannot be reparented.

To reparent a task stream, you must first convert it into a regular stream.

Create a task stream from a parent stream in the same depot

In the Streams tab, right-click the parent stream and select Create New Stream from 'stream_name'…
In the Stream:New dialog, define the new stream.
- Give the new stream a unique name.
  
  You cannot re-use task stream names, even if the task stream has been deleted.
- On the Basic Settings tab, select a Stream type of task.
- Verify that the depot where the task stream will be located is the current depot and that the parent stream is correct.
  
  See Creating streams for more information about the Stream:New dialog.
Verify that the new task stream appears correctly in the Stream Graph.

Refresh the Stream Graph view. You may need to select the task stream under Graph View Options. The task stream should appear as a child of its parent and be decorated with the task stream icon: .

Create a task stream in a different depot

Open the Stream:New dialog.

You can open the dialog by doing any of the following:
- Go to File > New > Stream
- In the Streams tab, right-click an existing stream and select Create New Stream from 'stream_name'.
- In the Streams tab, right-click on any white space in the Stream Graph and select New Stream.
In the Stream:New dialog, define the new stream.
- Give the new stream a unique name. You cannot re-use task stream names, even if the task stream has been deleted.
- On the Basic Settings tab, select a Stream type of task.
- Select the depot where the task stream will be located.
- Select the parent stream (in a different depot) from which the task stream will be branched.
  
  See Creating streams for more information about the Stream:New dialog.
Refresh the Stream Graph view to verify that the new task stream appears correctly.
- In the child stream’s depot, the parent stream and parent stream’s depot appear grayed out under Graph View Options, and the task stream appears as normal.
  
  When you select the child stream for viewing in the Stream Graph, it should appear as a child within its parent stream and parent depot hierarchy and be decorated with the task stream icon: .
- In the parent’s stream depot, the task stream appears grayed out under Graph View Options, but you can still select it for viewing in the Stream Graph.
  
  The task stream should appear as a child of its parent and be decorated with the task stream icon:
- When you are viewing the parent stream’s depot, you may want to see the actual depot location of the child task stream in the Stream Graph:
  - Select Stream Root as your Display stream option under Graph View Options. The full depot path appears in the stream node for each stream:
  - To change the size of the stream node to accommodate long depot paths, you can move the Stream node width slider.
    
    You can also select these display preferences in P4V > Preferences > Streams (Mac) or Edit > Preferences > Streams (Windows).

Create a task stream without a parent

Open the Stream:New dialog.

You can open the dialog by doing any of the following:
- Go to File > New > Stream.
- In the Streams tab, select the stream depot that will hold the new task stream, right-click an existing stream, and select Create New Stream from 'stream_name'…
- In the Streams tab, select the stream depot that will hold the new task stream, right-click on any white space in the Stream Graph, and select New Stream.
In the Stream:New dialog, define the new stream.
- Give the new stream a unique name.
  
  You cannot re-use task stream names, even if the task stream has been deleted.
- On the Basic Settings tab, select a Stream type of task.
- Select the depot where the task stream will be located.
  
  For a parentless stream this will usually be a stream depot that is dedicated to holding task streams. Contact your Helix Server administrator or project lead for information about the stream depot to use.
- Leave the parent stream field blank.
  
  See Creating streams for more information about the Stream:New dialog.
Verify that the new task stream appears on the Streams tab.

Parentless task streams do not appear in the Stream Graph, since there is no relationship to display. You can view parentless task streams in the Streams tab using List or Tree view.
Populate the new task stream.
- Open the Branch dialog by right-clicking the task stream in List or Tree view on the Streams tab and selecting Branch files….
- Whether you Specify source and target files or Use Branch Mapping, select the files that you want to branch to your new task stream as your source and the new stream as your target.
  
  A parentless stream will not appear in the browse dialog for the Choose target files/folders field. If you opened the Branch dialog by right-clicking the new task stream, it will appear in this field by default. Otherwise, you must enter the full depot path manually.
- If you didn’t do so as part of the branching process, submit the changelist containing the branched files.
  
  For more information about the Branch dialog, see Creating branches.
  
  You can also populate your new task stream using the Merge/Integrate dialog. For more information, see Merging files between codelines.
Verify that the new task stream is populated.
- When you are working in the new task stream workspace, the files should appear in the Depot view.
- When you get the latest revisions (sync) to your new task stream workspace, the files should appear in the Workspace view.

Convert a task stream to a regular stream

Important

Once you convert a task stream to a regular stream, you cannot convert it back.

To convert a task stream to a regular stream:

Right-click the task stream in the Streams tab and select Edit Stream 'stream_name'.
Change the Stream type to the regular stream type you want.
- Task streams with parents can convert only to release or development streams.
- A parentless task stream can convert only to a mainline stream.
- You cannot convert a task stream to a virtual stream.
Verify that the parent stream (if there is one) is in the same depot as the task stream to be converted.

Delete and unload task streams

You should always delete or unload a task stream after you are done with it. Your Helix Server administrator may also run a batch process to delete or unload inactive task streams on a regular basis. Note that any submitted files remain in the depot even after you delete a task stream. Note also that you cannot re-use the names of deleted task streams.

To delete a task stream:

Right-click the stream in the Streams tab (in graph, tree, or list view)
Select Delete Stream 'stream_name'.

Unloading transfers infrequently-used metadata from the versioning engine’s database files to a set of flat files in an unload depot. If you unload a task stream, you can reload it if you change your mind and want to use it again.

To unload a task stream:

Right-click the stream in the Streams tab (in graph, tree, or list view).
Select Unload stream 'stream_name'.

To reload an unloaded task stream:

Display the Streams tab in List or Tree view.
Select the Unloaded… icon in the filter pane to open the Unloaded Streams dialog, where you can filter for and select unloaded streams to reload.
Right-click the stream and select Reload Stream.

For more information about unloading, see the Helix Core Command-Line (P4) Reference.

Filter task stream files out of File History results

To filter out file revisions that were submitted to task streams when you view file history:

Go to P4V > Preferences(Mac) or Edit > Preferences (Windows) and select Files and History.
Select Hide files/revisions from 'task' streams (when following branch, copy actions).