How to Use Perforce — Streams 101
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.
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?
Want to learn more? Explore version control branching.