Perforce Public Knowledge Base - Streams Tutorial
Perforce Software logo
Reset Search



Streams Tutorial

« Go Back




Create a stream depot.

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

This tutorial will give you a peek at the commands and operations in version 2011.1.

There are visual tools for streams, but we are going to use the command line for this tutorial.

Let's assume our local environment is already configured to connect to a stream-savvy Perforce Server. Before we get started, we need to bootstrap a new client workspace. My trick for this is to create a new local directory, and in that directory, run:

% p4 client -o | p4 client -i

Okay, let's roll!

1. Creating a stream depot

Streams live in stream depots, so the first thing we need is a stream depot. Let's define one called Ace:

% p4 depot Ace

% p4 depots

We edit the default definition to make this a stream depot:

Depot: Ace 

Type:  local stream

(Note that the "we" in this step is a user with 'super' privileges. But from here on out, non-privileged users can run the commands I'll demonstrate.)

2. Creating a new mainline

Now we define a stream called //Ace/MAIN:

% p4 stream //Ace/MAIN

% p4 streams

% p4 stream -o //Ace/MAIN

By default, Perforce defines a development stream. With a simple edit we redefine it as a mainline stream:

Stream: //Ace/MAIN 
Parent: none 
Type:   development mainline

3. Importing files into the mainline

Having defined the stream, we can now switch our workspace to it:

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

% p4 client -o

% p4 info

(Note that the 'p4 workspace' command is the same as 'p4 client')

Our client view is now a view of the //Ace/MAIN stream. There aren't any files in that stream yet, so let's branch some from another depot location:

% p4 copy -v //depot/... //Ace/MAIN/...

% p4 submit -d "Seeding the Ace mainline"

% p4 dirs //Ace/MAIN/*

Now our mainline is full of files, ready for us and our colleagues to start working on them. Anyone who wants to work in the mainline can create their own workspace and switch it to the stream, just as we just did. Then they can run the usual p4 sync, p4 edit, and p4 submit commands, the same as in a non-stream workspace.

4. Branching a development stream from the mainline

Oh, but wait - let's say we don't want to do feature development work in the mainline. Instead, we want to work in a development stream. So let's branch a development stream from the mainline. We'll call it //Ace/DEV. First we define it, with //Ace/MAIN as its parent:

% p4 stream -P //Ace/MAIN //Ace/DEV

% p4 streams

% p4 stream -o //Ace/DEV

% p4 istat -s //Ace/DEV

This last command shows the integration status of the stream, in relation to its parent.

The defaults, in this case, produce exactly the stream definition we want:

Stream: //Ace/DEV 
Parent: //Ace/MAIN 
Type:   development

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

% p4 client -s -S //Ace/DEV

% p4 -ztag client -o

Again, 'p4 client' could be replaced with 'p4 workspace'.

And we populate the stream by branching its parent's files:

% p4 merge -S //Ace/DEV -r

% p4 submit -d "Branching from mainline"

This leaves our local workspace in sync with the //Ace/DEV branch, ready for us to start working on files.

5. Merging files from the mainline

While we're working on features in //Ace/DEV, other changes are being submitted to //Ace/MAIN. Here's how we merge those changes into the //Ace/DEV branch:

% p4 merge -S //Ace/DEV -r

% p4 resolve

% p4 submit -d "Merged latest changes"

(Yes, p4 merge is a new command. It does pretty much the same thing p4 integ does, but only after validating the relationship between a stream and its parent. This is another topic I'll be blogging about soon.)

6. Promoting our development work to the mainline.1

Let's say we've completed a development task in the //Ace/DEV stream. Now we'd like to promote our work to the parent stream.

"Promote" is simply another way of saying "copy up after merging everything down". So let's make sure we've merged everything down first:

% p4 merge -n -S //Ace/DEV -r 

All revisions already integrated.

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

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

% p4 sync

We run p4 sync after switching the workspace, because both streams have files in them at this point. (You'll be happy to know that p4 sync will be smart enough to swap out only the files that aren't the same in both streams.)

Finally, we copy content from the //Ace/DEV stream to its parent:

% p4 copy -S //Ace/DEV

% p4 submit -d "Here's our new feature"

Et voil -  our work in the //Ace/DEV stream has just been promoted to //Ace/MAIN.

7. Misc Advanced Stuff

a) Let have a look at the branch view.

This mapping is used for "copy" or "merge"

% p4 branch -o -S //Ace/Dev xxx
b) Stream views

Stream template views are used to generate views for stream clients.

% p4 streams -F Owner=user3

Add in the following fields see the effect on the generated the views:

Remapped, Ignored

Try the same on the Path field by adding isolate, import and exclude.

Related Links



Was this article helpful?



Please tell us how we can make this article more useful.

Characters Remaining: 255