How to Use Perforce — Streams 101

Looking for how to use Perforce version control –– Helix Core? It’s all about Streams.

Streams helps streamline branching and merging operations to help automate your development and release processes. It eliminates the guess work for developers wondering where to merge their branch. And it keeps your mainline and release streams more stable.

So, how does it work? In this blog we’ll review how to:

• Create a stream depot.
• Create a mainline stream.
• Import files from an existing depot into our mainline.
• Branch a development stream from the mainline.
• Merge files from the mainline to the development stream.
• Promote the development stream to the mainline.

Watch Our Streams Quickstart Video >>

For this example, we will use the command line. But you can also use Streams with our Helix Visual Client (P4V), Visual Studio, and more.

Let's assume our local environment is already configured. Before we get started, we need to create a new workspace. You can create a new local directory and run:

% p4 workspace -o | p4 workspace -i

Now we are ready!

How to Use Perforce | Creating a Stream Depot

Streams live in stream depots. We are going to create one called ‘Ace.’

p4 depot Ace

Then you can edit the default definition to make this a specific stream depot:

Depot: Ace
Type: stream

To create a stream depot, you will need 'super' privileges in Helix Core. All other commands are available for all users.

How to Use Perforce | Creating a New Mainline

The mainline stream is the foundation for development and release streams. Depending on your branching strategy, you may have just one mainline, or segment out development.

To define a mainline stream, run:

p4 stream -t mainline //Ace/MAIN

Now that the mainline stream is created, you can start working on files.

Watch the demo below to see what branching looks like in Perforce Streams.

How to Use Perforce | Importing Files into the Mainline

Once the stream is defined, switch your workspace to it:

p4 workspace -sf -S //Ace/MAIN

Now our client is a view of the //Ace/MAIN stream, we can add files. For this example, we are branching some files from another depot location:

p4 populate //depot/projects/ace/trunk/... //Ace/MAIN/...

Now our mainline has files, it’s ready for development. Anyone who wants to work in the mainline can create their own workspace and switch it to the stream. Then they can run the usual p4 sync, p4 edit, and p4 submit commands to their workspace.

How to Use Perforce | Streams Workflow

The most common workflow for developers is to create a development stream from the mainline. As they work, it is important to merge down changes from the mainline. Once their code is ready to be incorporated into the mainline, it can be copied up.

This principle –– merge down, copy –– is built into Streams.  And it’s easy to see how code should flow using the Stream Graph in P4V.

Let's branch a development stream from the mainline called //Ace/DEV. First, we define //Ace/MAIN as its parent:

p4 stream -t development -P //Ace/MAIN //Ace/DEV

We now can switch our workspace to //Ace/DEV:

p4 workspace -s -S //Ace/DEV

The development stream is populated by branching the parent's files:

p4 populate -S //Ace/DEV -r

Now our local workspace is in sync with the //Ace/DEV branch and it’s ready for us to start working on files.

Merging Files from the Mainline

While we’re working on features in //Ace/DEV, other changes are being submitted to the mainline. To So let's preview the merge to make sure that we've merge everything down first:

p4 sync
p4 merge -S //Ace/DEV -r
p4 resolve
p4 submit -d ”Merged latest changes”

Promoting Development Work

Development streams should only last as long as necessary. Once our work is complete in the //Ace/DEV stream, the work needs to be promoted to the parent stream. For our example, it is the mainline.

Promote is simply another way of saying ‘copy up changes after merging everything down.’ In the Stream Graph, the red arrows indicate when changes are available to be merged. So let's preview the merge to make sure that we've merge everything down first:

p4 merge -n -S //Ace/DEV -r
All revisions already integrated

Now let's switch our workspace back to //Ace/MAIN:

p4 workspace -s -S //Ace/MAIN
p4 sync

Running p4 sync after switching the workspace ensures both streams’ files are the same versioned. Finally, copy changes from the //Ace/DEV stream to the parent:

p4 copy -S //Ace/DEV
p4 submit -d ”Here’s our new feature”

This tiny tutorial is just the beginning. Streams is flexible and can easily be customized to support your development and release strategy. And as your team grows, Helix Core can provide increased visibility into large teams working on even bigger projects.

Not a Helix Core customer?

TRY FREE

Want to learn more? Explore version control branching.