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

Chapter 3
Using P4Sandbox with the Command-Line Client
This chapter tells you how to use the Perforce Command-Line Client (p4) to perform P4Sandbox tasks. To perform these tasks, you must first configure a P4Sandbox; see Setting Up P4Sandbox.
This chapter provides basic information about commands you use with a P4Sandbox, including command-line syntax, arguments, and flags.
For a comparison of P4Sandbox and Git terms and tasks, see Comparing Git and P4Sandbox commands.
P4Sandbox uses two types of commands:
This category includes two subcategories: the additional and modified commands.
P4Sandbox-specific commands
P4Sandbox adds several commands to a category p4sandbox (listed in general usage order):
Additional p4 commands
P4Sandbox adds several p4 commands that work only within a P4Sandbox context (listed in alphabetical order):
Modified p4 commands
P4Sandbox extends the behavior of the following p4 commands when executed within a P4Sandbox context (listed in alphabetical order):
p4 integrate(p4 integ)
Using P4Sandbox commands
This section provides general usage information for the P4Sandbox commands.
All information in this chapter specifically describes a command's behavior while operating in a P4Sandbox context. For the modified commands, see the Perforce Command Reference for general information about a command and its behavior in a non-P4Sandbox context.
TCP connection requirement
You are not required to have an active TCP connection when issuing commands, unless you are copying changes to and from a shared service.
Prohibited mirror stream update commands
You cannot use the following p4 commands to update a mirror stream with changes from the local stream:
You must use either p4 copy or p4 integrate to update the mirror stream.
Invalid commands
Because you are normally the sole user and administrator of your P4Sandbox, commands for groups and certain commands for administrators may be essentially invalid.
Accessing help
The following commands display lists containing P4Sandbox-specific commands and extended p4 standard commands. The enhanced standard p4 commands include additional P4Sandbox explanatory text at the bottom of the help documentation, in a section entitled p4sandbox extension.
To access P4Sandbox p4 help documentation, issue one of the following commands:
You must be connected to an active P4Sandbox to use p4 help sandbox. See "Starting P4Sandbox" below.
Starting a P4Sandbox
You must start a P4Sandbox to use it; it is not automatically started by any other process initialization.
To start a P4Sandbox, type:
p4sandbox start
Working in a specific client write mode
The client write mode you set for your P4Sandbox determines whether files are read-only or editable, and whether you must issue the p4 edit command to change files.
For more commands and information about working in allwrite or noallwrite mode, see Client mode dependent commands.
Merging down changes from the shared service
You can perform a mergedown of shared service changes to update the entire P4Sandbox or only the mirror stream.
Updating P4Sandbox with shared service changes
To merge down from the mirror stream, type:
p4 mergedown
Resolving a mergedown that has conflicts
When you perform a mergedown that results in conflicts, you must resolve and submit all conflicts to update P4Sandbox with the latest changes from the shared service.
Example: This example shows how to update a P4Sandbox with shared service changes when conflicts exist.
p4 resolve
p4 submit
Updating only the mirror stream with shared service changes
When you are connected to your company's network, use p4 pull to retrieve the latest changes for eventual merging into your code, even if your P4Sandbox is not connected to the network. For example, you issue the p4 pull command before disconnecting from the company network for a business flight. On the flight, you work in your P4Sandbox, merging down the changes from the mirror stream to the local stream before working in the local stream.
To update the mirror stream with shared service changes, type:
p4 pull
Copying up changes to the shared service
When you copy up and submit changes from your local stream to your mirror stream, the mirror stream automatically copies up and submits changes to the shared service.
Example: This example shows how to copy up changes to the shared service.
p4 copyup
p4 submit
If you create a script to copy up changes to the mirror stream automatically, be sure to include logic to first validate the synchronization status of the shared service and mirror stream before copying changes from a local or task stream to the mirror stream.
If you implement P4Sandbox connected to a shared service, be sure to periodically copy up or shelve important work to the mirror stream. This insures that you have the latest file versions available as backups on the shared service, in case of failures or accidents.
Resolving a copy up that has conflicts
When a copyup attempt results in conflicts, you must correct the conflicts in the local stream before attempting to copy up changes again to the mirror stream.
Example: This example shows how to resolve a copyup that results in conflicts. Note that you must resolve conflicts in the local stream and issue the p4 submit command twice—once to the local stream and once to the mirror stream.
(receive conflicts)
p4 mergedown
p4 resolve
p4 copyup
p4 submit
Working with streams
This section discusses how to use the P4Sandbox streams functionality.
Adding a task stream
To create and switch to a new stream, type:
p4 copy //streams/parent/... //streams/stream/...
Viewing stream information
To show the currently active stream name, type:
p4 switch
To list all streams in the P4Sandbox, type:
p4 streams
Switching between streams
When you switch between streams, P4Sandbox automatically shelves any in-progress work in the currently active stream before switching to the new stream.
To switch streams, type:
p4 switch stream name
Example: This example shows how to determine the streams in a P4Sandbox, how to determine the currently active stream, and how to switch between streams (specifically, from the mirror stream to the local stream).
C:\Users\jblack\sandboxes\sandbox1666>p4 streams
Stream //streams/bugbox development //streams/local 'bugbox'
Stream //streams/local development //streams/mirror 'local'
Stream //streams/mirror mainline none 'mirror'
C:\Users\jblack\sandboxes\sandbox1666>p4 switch local
Client WIN-JBLACK switched to //streams/local.
//streams/local/jblack/main/0224.txt#1 - unshelved, opened for edit
Copying changes between task streams
Copy or merge changes between task streams using one of these four commands:
P4Sandbox automatically switches to the destination stream before performing any of these commands.
Deleting a task stream
You cannot completely delete a stream because Perforce always retains a stream's history. Deleting a stream only deletes the stream specification, not any of the files that were in the stream. The files and their history remain in Perforce and continue to appear in the shared service.
Deleting a stream is possible, however, by issuing the p4 obliterate and p4 change -d commands. For more information on using these commands, see the Perforce Command Reference.
Working with shelving
This section discusses how to use the P4Sandbox shelving functionality.
P4Sandbox propagates any shelving action that you perform while in a 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.
For more information about this capability, see Automatic and manual shelving.
Shelving and unshelving in-progress work
P4Sandbox automatically shelves and unshelves in-progress work when you switch from one task to another by switching between streams; see Switching between streams.
To shelve work, type:
p4 shelve
This command invokes a text editor window and displays a changelist. Enter a changelist description and save the text file to complete the command.
Example: This example shows how to shelve work to the shared service from a local stream.
p4 copyup
p4 shelve
To unshelve work, type:
p4 unshelve -s changelist#
You must include the pending changelist number that contains the shelved files to complete the command.
Deleting a shelf
To delete a shelf, do the following:
(Optional) Use p4 unshelve -s changelist# to unshelve any work you want to retain before deleting the shelf and its associated changelist.
Ensure that the changelist does not contain open files. Issue p4 opened -c changelist# to view this information. Resolve any open files, such as by moving them to another changelist or reverting them.
Example: This example shows how to delete a shelf and its changelist.
p4 shelve -d -c changelist#
p4 change -d changelist#
Viewing shelf information
To list the shelves in a P4Sandbox, type:
p4 changes -c client -s shelved
To display shelved content, type either of the following commands:
p4 describe -S changelist#
p4 files @=changelist#
Reviewing file and directory information
This section discusses how to retrieve information about changelists, files, and directories.
Determining files in your workspace
The table below list commands for reviewing changelist and file information.
p4 describe -S changelist#
p4 files dir/...
p4 files //streams/mirror/...
p4 files @=changelist#
p4 filelog
Stopping a P4Sandbox
To stop a P4Sandbox, issue one of the following commands:
See also
For more information about these commands and their options, see P4Sandbox Command Reference.
You can use these commands in scripts to automate your work. For more information about using Perforce commands in scripts, see the P4 User's Guide, "Scripting and Reporting."

Previous Table of Contents Index Next

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