Working with task streams

A task stream is well suited for a limited task, such as fixing a bug or developing a small feature. A task stream is a lightweight branch that affects a small number of files relative to the total number of files in the branch. A task stream is often temporary, and deleted or unloaded when its changes have been integrated.

Task streams can help Helix Core Server performance by keeping the amount of repository metadata to a minimum.

Overview

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.

1. Create a task stream from a parent stream.
2. Populate the task stream.
3. Work on a new feature and submit the code.
4. Merge down changes from the parent stream to the task stream.
5. Copy your changes up.
6. (Optional) Delete or unload the task stream. However, if you edit more than half the files in your task stream, that stream no longer reduces repository metadata. In this case, consider converting your task stream to a development stream. See Convert a task stream to a regular stream.

Using a task stream is 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 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 administrator or project lead can 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. However, you can Convert a task stream to a regular stream and that regular stream can be reparented.

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

1. In the Streams tab, right-click the stream that will be the parent stream of the task stream.
2. Select Create New Stream from 'stream_name'…​

3. In the Stream:New dialog, define the new stream.

   On the Basic Settings tab, give the new stream a unique name. You cannot re-use task stream names, even if the task stream has been deleted. 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. For more information about the Stream:New dialog, see Creating streams . (Optional) Select "Branch files from parent on stream creation". Click OK.

4. Verify that the new task stream appears in the Stream Graph.

   Refresh the Stream Graph view. Select the task stream under Graph View Options. The task stream appears as a child of its parent and is decorated with the task stream badge

Create a task stream in a different depot

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

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

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

In this example, we create a task stream without a parent stream. We populate this parentless task stream with files from a classic (non-stream) depot.

1. 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 Graph tab, select the depot that will hold the new task stream, right-click on any white space in the Stream Graph, and select New Stream

2. In the Stream:New dialog, define the new stream.

   On the Basic Settings tab, for Stream name, give the new stream a unique name. You cannot re-use task stream names, even if the task stream has been deleted. For Stream type, select task. Under Change propagation, the checkboxes can be selected or cleared because "To parent" and "From parent" are not relevant to a task stream without a parent. For Depot, select the Depot that your administrator indicated to use for a parentless task stream. For Parent stream, make sure the field is empty. For Location, provide a path in the format //depotName/streamName Clear the checkbox for Create a workspace to use with the stream. Clear the checkbox for Branch files from parent on stream creation. Click OK.

3. On the P4V toolbar, click Refresh.

4. Verify that the new task stream appears on the Streams tab. (Parentless task streams do not appear in the Stream Graph because there is no relationship to a parent stream.)

5. On the Streams tab, right-click the new stream and select New workspace... to create a workspace for the new stream.
   
   then click OK.
   

6. Populate the stream.

   On the Streams tab, right-click the new stream and select Branch Files…​ so you can configure the Branch dialog. For Branch method, use Specify source and target files or Branch method to assign the location of the source files and target files. Select Add files to pending changelist or Automatically submit after branching files, then click Branch. On the Workspace tab, the new stream is populated with files. If you selected Add files to pending changelist, you can now 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. See Merging files between codelines.

7. Verify that the new task stream is populated.

   • When you are working in the new task stream workspace, the files appear in the Depot view.
   • When you get the latest revisions (sync) to your new task stream workspace, the files appear in the Workspace view.

Convert a task stream to a regular stream

To convert a task stream to a regular stream, such as a development stream:

1. Right-click the task stream in the Streams tab and select Edit Stream 'stream_name'.

2. 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.
3. 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

Important considerations

• You should always delete or unload a task stream after you are done with it. Your Helix Server administrator can also run a batch process to delete or unload inactive task streams on a regular basis.

• Any submitted files remain in the depot even after you delete a task stream.

• The names of deleted task streams cannot be reused.

Deleting a task stream

To delete a task stream:

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

Unloading a task stream

Unloading transfers infrequently-used metadata from the Helix Core Server database files to a set of flat files in a special depot of type unload. 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:

1. Make sure that an unload depot is available.
2. Right-click the stream in the Streams tab (in graph, tree, or list view).
3. Select Unload stream 'stream_name'.

To reload an unloaded task stream:

1. Display the Streams tab in List or Tree view.
2. 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.
3. 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:

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