Task streams

Consider using Sparse streams instead of task streams because sparse streams have significant advantages over task streams.

It is best practice to use sparse streams instead of task streams unless you need to use a feature that sparse streams do not support.

A task stream is for a limited task, such as fixing a bug or developing a small feature. A task stream should involved only a small number of files relative to the total number of files in the branch.

A task stream should be temporary, and deleted or unloaded when its changes have been integrated. The deletion or unloading of each task stream 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 development 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 with files from a non-stream depot.

• 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 development 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 box, 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 box, see Create 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 box.

   You can open the dialog box 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 box, 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 Create streams for more information about the Stream:New dialog box.

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 with files from a non-stream depot

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

1. Open the Stream:New dialog box.

   You can open the dialog box 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 box, 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 box. 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 box, see Create branches. You can also populate your new task stream using the Merge/Integrate dialog box. See Merge 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 development stream

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

2. Change the Stream type to development.

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

• Delete or unload your task stream as soon as its changes have been integrated. Your Helix Core 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.

Delete 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'.

Unload 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 box, 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 from File History

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