To map a set of files from source to target, you can create a branch mapping and use it as an argument when you issue the p4 integrate command. To create a branch mapping, issue the p4 branch branchname command and specify the desired mapping in the View: field, with source files on the left and target files on the right. Make sure that the target files and directories are in your client view. Creating or altering a branch mapping has no effect on any files in the depot or client workspace. The branch mapping merely maps source files to target files.

To use the branch mapping to create a branch, issue the p4 integrate -b branchname command; then use p4 submit to submit the target files to the depot.

Branch specifications can contain multiple mappings and exclusionary mappings, just as client views can. For example, the following branch mapping branches the Jam 1.0 source code, excluding test scripts, from the main codeline.

Branch:   jamgraph-1.0-dev2release

View:
    //depot/dev/main/jamgraph/...       //depot/release/jamgraph/1.0/...
    -//depot/dev/main/jamgraph/test/... //depot/release/jamgraph/1.0/test/...
    //depot/dev/main/bin/glut32.dll     //depot/release/jamgraph/1.0/bin/glut32.dll

To create a branch using the preceding branch mapping, issue the following command:

p4 integrate -b jamgraph-1.0-dev2release

and use p4 submit to submit the changes.

To delete a branch mapping, issue the p4 branch -d branchname command. Deleting a branch mapping has no effect on existing files or branches.

As with workspace views, if a filename or path in a branch view contains spaces, make sure to quote the path:

//depot/dev/main/jamgraph/... "//depot/release/Jamgraph 1.0/..."

To branch using file specifications, issue the p4 integrate command, specifying the source files and target files. The target files must be in the client view. If the source files are not in your client view, specify them using depot syntax.

To create a branch using file specifications, perform the following steps:

Before you can work in a stream, you must create a workspace associated with the stream. When you associate a workspace with a stream, Perforce generates the workspace view based on the structure of the stream. You never need to edit the workspace view (and, in fact, cannot manually alter it). If the structure of the stream changes, Perforce will update the views of workspaces associated with the stream on an as-needed basis.

(Suggestion: When assigning names to stream-associated workspaces, adopt a naming convention such as user_depot_streamname. For example, bruno_projectX. If you regularly switch between client workspaces associated with different types of streams, you may also find it useful to append the stream type, to your workspace name, for example, bruno_projectX_main and bruno_projectX_dev.)

To create a workspace for a stream:

Now you can populate the mainline with files.

If you do not need to preserve the historic connection between the source files and the files in the new mainline stream, simply add them. To add files to the mainline stream:

To verify that the files are set up to be added correctly, issue the p4 opened command. To populate the stream, submit the changelist in which the files are open.

You can branch files from other stream depots, classic depots, or remote depots. If you populate the mainline by branching, Perforce preserves the connection between the revision history of the source and target files. Your workspace must be set to one associated with the target stream (example: p4 set P4CLIENT=bruno_projectX_main).

To populate the mainline by branching, issue the p4 copy command, specifying source and target. Example:

p4 copy -v //mysourcedepot/mainline/... //ProjectX/main/...

(In this example, the -v flag improves performance by updating the service without copying files to the workspace.) Perforce displays a series of "import from" messages listing the source and target files, and opens the file in a pending changelist. To preview the results of the operation without opening files, specify the -n flag. To undo an erroneous copy operation, issue the p4 revert command; for example: p4 revert //ProjectX/main/...)

To verify that the files are set up to be added correctly, issue the p4 opened command. To populate the stream, p4 submit the changelist in which the files are open.

If you are populating an empty stream, you can simplify this process by using p4 populate. For example:

p4 populate //mysourcedepot/mainline/... //ProjectX/main/...

does the same thing as p4 copy -v followed by a p4 submit. If you are unsure of the results of p4 populate, use p4 populate -n, which previews the result of the command.

To update a stream with changes from a more stable stream, issue the p4 merge -S source-stream command, resolve as required, and submit the resulting changelist. By default, you cannot copy changes to a more stable stream until you have merged any incoming changes from the intended target. This practice ensures that you do not inadvertently overwrite any of the contents of the more stable stream.

Assuming changes have been checked into the mainline after you started working in the development stream (and assuming your workspace is set to a development stream), you can incorporate the changes into the development stream by issuing the following commands:

p4 merge -S //projectX/dev -r
p4 resolve
p4 submit -d "Merged latest changes"

After merging, your stream is up to date with its more stable parent or child. Assuming you've finalized the changes you want to make in the development stream, you can now promote its new content with no danger of overwriting work in the target stream. The "copy" operation simply propagates a duplicate of the source to the target, with no resolve required. For example, (and assuming your workspace is set to a mainline parent stream) to promote changes from the development stream to its parent mainline, issue the following commands:

p4 copy -S //projectX/dev
p4 submit -d "Check my new feature in"

You might need to propagate a specific change between two streams that do not have a natural parent-child relationship, for example, to obtain an in-progress feature or bug fix from a peer development stream. To merge from or copy to such a stream, you can reparent your stream by editing its specification and setting the Parent field to the desired source or target. This practice is not considered optimal but might be necessary.

Typically you define a workspace for each stream that you intend to work in. However, if your streams contain extremely large numbers of files (tens to hundreds of thousands, for example), this approach can require a time-consuming sync when you switch to working in a stream that has changed a lot since the last time you worked in it. If the structure of your streams is consistent and most files are identical, you can avoid this problem by reassociating your workspace with the stream you are switching to instead of using different workspaces for both streams. After you change the stream with which the workspace is associated, sync to obtain any files that differ.

To change the stream associated with a workspace, issue the following command:

p4 client -s -S //streamdepot/ streamname

For large projects, even consistently-organized streams may not sufficiently restrict workspace views. In large organizations, there are often many groups who are concerned with only a small subset of a project's files. In classic Perforce, these users would manually restrict their client workspace's view to include only the desired subset. Streams offers an alternative; use a virtual stream as a filter:

For example, if ongoing development work is occurring in an //Ace/dev stream:

Stream:  //Ace/dev
Parent: //Ace/main
Type:   development
Paths:
    share ...

Then a user who is working only with the documentation for the product (rather than all of the assets associated with the project) could create a virtual stream that includes only those files under //Ace/dev/docs/..., as follows:

Stream:  //Ace/devdocs
Parent: //Ace/dev
Type:   virtual
Paths:
    share docs/...

The user can then can switch his or her client workspace to the devdocs virtual stream with the following command:

p4 client -s -S //Ace/devdocs

When using the devdocs workspace, the user's client workspace view is automatically updated to include only the material in //Ace/dev/docs/... and any changes he or she makes in //Ace/devdocs are automatically propagated back to the original //Ace/dev codeline without the need to manually run p4 copy or p4 integrate.

The StreamAtChange option in the workspace specification lets you set a stream workspace to sync a stream using the stream's view as of a specific changelist. This gives you the ability to see a "back-in-time" view of your stream. This is helpful when you want to see what the stream view was at a particular point in time, especially if your stream definition changes a lot. When you use the StreamAtChange option, you cannot submit changes to the files in the stream, since your workspace files are not at the head revision.

To set a stream workspace to sync as of a specific changelist:

For more information, see the P4 Command Reference, "p4 client".