Previous Table of Contents Index Next
Perforce 2012.3: P4Sandbox User's Guide



Chapter 1
Purpose
Using P4Sandbox lets you have the private branching and offline capabilities of a distributed version control system with the advantages of a shared version control system.
P4Sandbox lets you create and maintain private, local codelines for work such as code experimentation and bug fixes. You can optionally connect these local codelines to a Perforce shared service.
Features and functionality
P4Sandbox offers the following features and functionality:
Connection-independent versioning (also called always-on versioning): P4Sandbox enables you to check changes in and out without requiring an active connection to a shared service. You connect to a shared service when merging changes or sharing your work.
Private local codelines: You can create codelines (called local streams) within your P4Sandbox for specific tasks, such as bug fixes for a particular release.
Integration with other Perforce products: P4Sandbox integrates with the Perforce Command-line Client (p4) and graphical client applications such as P4V and P4Eclipse.
P4Sandbox stream architecture and components
P4Sandbox operates on Perforce streams. Of the four stream types, the two stream types you primarily use in P4Sandbox are:
Mainline: The base or trunk of a stream system.
Development: For long-term projects and new features. A development stream is less stable than its parent stream.
The other stream types are release (for bug-fixing, testing, and release distribution) and virtual (for filtering other stream types). For more information about Perforce streams, see the resources listed in See also.
P4Sandbox consists of the following components:
Shared service (optional): Your enterprise's main Perforce server; the one server that everyone shares. You can use P4Sandbox with non-streams-enabled (classic) or streams-enabled shared services. This component is optional, as you can use P4Sandbox without a shared service connection.
Mirror stream: A mirror stream is any mainline stream in P4Sandbox associated with a shared service. As the mirror stream mirrors the shared service, the mirror stream is the staging ground for pushes and pulls between the shared service and a local stream in P4Sandbox. Mirror streams are always mainline streams.
Local stream: Any stream in P4Sandbox that is not a mirror stream. The term includes mainline streams that are not associated with shared services, as well as any development streams. Most local streams are development streams, descendants of a mirror stream. P4Sandbox automatically creates one local stream for a P4Sandbox implementation. A task stream is the term used in this guide for a local stream that you intend to use for a single specific task, like a bug fix.
The figure below shows P4V connected to a P4Sandbox that has a parent mirror stream (named mirror) with child local streams (named bugs and dev 1.0). The bugs local stream has a child local stream (or task stream) bugs_az. P4Sandbox automatically created the mirror and local streams, and the local stream was renamed to dev 1.0—you can see this in the Depot tab view, where the stream appears as local (dev 1.0). The bugs and bugs_az streams were manually added.
For more information on the installed components, see P4Sandbox installation components.
Implementation configurations and restrictions
In general, most users use P4Sandbox in a straightforward configuration, either connected to a shared service or as a standalone implementation. However, you can also implement P4Sandbox in various configurations according to your requirements, such as multiple P4Sandboxes associated with multiple workspaces and multiple shared services.
Be aware that for an implementation that includes a shared service, P4Sandbox enforces certain behavior. We discuss these restrictions in the following three sections.
Merge down and copy up paradigm
P4Sandbox enforces a strict merge down and copy up paradigm, as follows:
For more information on the Perforce stream merge down and copy up paradigm, see the articles listed in the Additional Resources section of the Perforce Stream Adoption Guide:
http://www.perforce.com/product/product_features/perforce_streams
Local stream conflict resolution
In P4Sandbox, conflict resolution cannot occur in the mirror stream. You must resolve conflicts in the local stream before submitting files to the mirror stream.
Connected P4Sandbox copy restrictions
You can only copy changes between a shared service and a P4Sandbox. You cannot copy changes between two or among multiple P4Sandboxes that are connected to a shared service.
P4Sandbox usage
This section discusses P4Sandbox's standard functionality for task streams, shelves, and submissions.
Task stream creation
Once you have created a P4Sandbox, you can create task streams for your own work. Task streams are local streams that are small, focused containers for work such as individual features, bug fixes, and code experiments. You can quickly create and use task streams, and also quickly switch between streams because Perforce keeps track of the identical files between streams. (Generally, most files are identical, so switching streams involves changes to very few files.)
Task streams are an effective way to isolate, develop, and save work before it is ready to be shared on the shared service. This is useful in certain situations, such as your company or team having code policies on what can and cannot be pushed to the shared service. For example, if you are prohibited from checking in code that does not pass regression testing, you can save it in a task stream until it is ready to be submitted to the shared service.
Note that task streams are a concept, not a specific stream type. There is no mechanical difference between a local stream and a task stream; the difference is solely in usage and not in how P4Sandbox handles the stream.
Automatic and manual shelving
Shelving is the process of temporarily storing files on a Perforce server without checking in a changelist. The P4Sandbox shelving feature enables you to switch tasks and save work-in-progress without first having to check in any changes.
P4Sandbox has the following types of shelving functionality:
Automatic: Shelving that P4Sandbox performs in the background when you switch among task streams and workspaces and have unsubmitted changes.
Manual: Shelving that you perform when you switch among task streams and workspaces and have unsubmitted changes, or from within the mirror stream as a backup of your work.
P4Sandbox propagates any shelving action that you perform while in the mirror stream to the shared service. This means you can have pending changelists with shelved files existing in both the shared service and your P4Sandbox. Besides giving you the ability to save work-in-progress, this capability facilitates code review and pre-flight builds.
For more information on Perforce's shelving functionality, see the P4 User's Guide, "Shelving work in progress."
Changes and changelist submission
P4Sandbox transfers only a single submission containing a single changelist to the shared service; it does not propagate any intermediate changes made in the task stream. For example, your P4Sandbox task stream contains versions 1-10 of a change, with multiple corresponding changelists. When you submit this change to the shared service, the shared service contains only version 10 and the final submitted changelist.
If you implement P4Sandbox to work with Perforce's jobs functionality, P4Sandbox copies up job fixes to the shared service. For more information, see p4 submit and Managing jobspecs and jobs.
Differences between using p4 and P4V
This section discusses differences when using P4Sandbox with p4 versus a graphical client application's P4V integration.
Functional differences
p4 supports more functionality than P4V does, especially for administrative tasks. This includes (but is not limited to) the following actions, shown in the table below with the appropriate command:
P4V is better at presenting certain information in a more easily-understood way for most users. For example, P4V's Time Lapse View provides a more intuitive visual representation of merge and copy history than the p4 annotate command provides. P4V also better facilitates interactive usage, such as moving the Workspace icon in the Streams Graph view to another stream to change the active workspace.
For more information, see P4Sandbox Command Reference.
Directory differences
When you create P4Sandboxes using the P4Sandbox Configuration Wizard, the wizard automatically creates a sandboxes directory that contains necessary files on your machine's hard drive. You can edit the directory's default location during the configuration process. When you use p4 to create P4Sandboxes, P4Sandbox does not create this directory, as it is not necessary.
P4Sandbox administration
A major difference between P4Sandbox and other Perforce products is the role of the Perforce Administrator (or superuser). With P4Sandbox, you are the primary administrator of your P4Sandbox, particularly if you configure it as a standalone implementation. A Perforce Administrator's P4Sandbox control is limited to the point of interaction—the shared service. Because Perforce Administrators have limited visibility into the interaction between a P4Sandbox and the shared service, they can only perform general tasks over P4Sandboxes, such as running reports and viewing which files users have exchanged with the shared service.
For more information, see Administering P4Sandbox.
See also
See the following related information and related products:
http://www.perforce.com/product/product_features/perforce_streams
P4 User's Guide, "Codelines, Branching and Streams"
P4V Online Help, "Working with Streams"


Previous Table of Contents Index Next

Perforce 2012.3: P4Sandbox User's Guide
Copyright 2012-2013 Perforce Software.