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



Appendix A
This chapter discusses P4Sandbox commands and gives specific command syntax. It also provides tables that list equivalent Git commands.
Extended p4 commands
P4Sandbox extends the functionality of the following standard p4 commands:
All information in this chapter describes a command's behavior while operating in a P4Sandbox context. See the Perforce Command Reference for general information about a command and its behavior in a non-P4Sandbox context.
p4 admin stop
Synopsis
Stops a connected P4Sandbox.
Syntax
p4 admin stop
Description
p4 admin stop requires an active TCP connection to stop a connected P4Sandbox.
For complete command documentation, see the Perforce Command Reference, p4 admin.
Options
None
Related Commands
To stop a P4Sandbox that is not connected to a TCP connection
p4 copy
Synopsis
Copy changes from a source stream to a target stream; also, create the target stream, as necessary.
Syntax
p4 copy [options] fromFile[revRange] toFile
p4 copy [options] -S stream [-P parent] [-F] [-r] [toFile[revRange] ...]
Description
p4 copy performs the following actions:
Automatically creates and configures the target stream in the P4Sandbox, if the target stream does not exist
Note that when the source refers to files in a remote depot (that is, files in a shared service), the target must refer to a location within a new or existing mirror stream in the P4Sandbox. P4Sandbox records a mapping that links these two locations as part of the copy process.
For complete command documentation that includes global options, see the Perforce Command Reference, p4 copy. See also Connected P4Sandbox copy restrictions in the Overview.
Options
fromFile[revRange] toFile
See the comprehensive description for these arguments in the Perforce Command Reference for p4 integrate.
-S stream [-P parent] [-F] [-r] [toFile[revRange] ...]
P4Sandbox automatically switches your workspace to the destination stream before integrating. If the target is a mirror stream, P4Sandbox automatically switches your workspace back to the source stream.
Related Commands
To integrate files from a source to a target and automatically create target streams
p4 copyup
Synopsis
Copy changes from the current stream to its parent stream.
Syntax
p4 copyup
Description
p4 copyup copies changes from the current stream to its parent.
p4 copyup does not submit. After issuing this command, you must execute a separate p4 submit command.
Options
None
Related Commands
p4 counter
Synopsis
Access, set, increment, or delete a persistent variable.
Syntax
p4 counter p4sandbox_countername value
Description
Use the p4 counter command with the provided P4Sandbox-specific options to manage default backup and pulling interval behavior.
For complete command documentation that includes global options, see the Perforce Command Reference for p4 counter.
Options
Controls how many checkpoints and journals P4Sandbox retains. The default is 3.
Controls how frequently P4Sandbox runs a checkpoint and journal rotation in the background. The value is in hours and the default is 24 (that is, daily). A blank (no value) or a zero (0) value indicates that P4Sandbox does not perform automatic checkpoint and journal rotation. We recommend that you do not disable this feature.
Controls how frequently P4Sandbox runs a p4 pull all command in the background. The value is in hours and the default is blank, where a blank (no value) or a zero (0) indicates that P4Sandbox should not perform automatic pulls.
p4sandbox delete
Synopsis
Permanently delete a P4Sandbox.
Syntax
p4sandbox delete [-y] [-r p4dDir | [-a | all] ]
Description
p4sandbox delete performs the following actions:
Permanently removes a P4Sandbox. This includes the entire p4dDir containing all metadata and versioned files.
Permanently removes the P4Sandbox entry from the list of known P4Sandboxes contained in the platform-specific .p4sandbox-list file.
Options
-r p4dDir
Delete all P4Sandboxes listed in the p4sandbox-list. This option also removes the p4sandbox-list file.
Usage Notes
By default, p4sandbox delete displays a preview of the results. To execute the operation, you must specify the -y flag.
C:\Users\jblack\sandboxes> p4sandbox delete -y -r C:\Users\jblack\sandboxes\sandbox1666\.p4sandbox
Related Commands
p4sandbox init
Synopsis
Create and start the first instance of a new P4Sandbox.
Syntax
p4sandbox init [options]
Description
If you do not specify options for this command, p4sandbox init creates a local P4Sandbox in directory .p4sandbox, listening on port localhost:1666, with a workspace root in the current directory.
If you set the P4CONFIG environment variable, this command also creates .p4config file (which may use a user-defined name) in the current directory and sets up a workspace.
Options
-p port
-r p4dDir
-R clientDir
Set the path to the workspace root for the client that p4sandbox init creates. Default is the current working directory.
Note: -R clientDir implies -r clientDir/.p4sandbox unless -r also specified.
-u user
-c client
Specify the client to create, overriding the value of $P4CLIENT. If $P4PORT is defined and P4Sandbox can read a similarly named client from that server, p4sandbox init copies options from the client on $P4PORT into the new client on the P4Sandbox.
-w stream
Default is //streams/local
Usage Notes
Use p4sandbox init only for the initial P4Sandbox creation. Use p4sandbox start to launch an existing P4Sandbox.
If you issue p4sandbox init from an existing .p4sandbox directory, the command fails.
If you issue p4sandbox init from another Perforce workspace directory (like an existing shared service workspace directory), P4Sandbox may partially overlap or completely overwrite the existing workspace's configuration.
If the workspace directory originally was the shared service directory, it is now a P4Sandbox root directory, and this scenario may result in clobber issues when attempting to synchronize changes.
To configure P4Sandbox for Unicode mode, use the p4sandbox init command with the appropriate options. For example, to configure P4Sandbox for UTF-32 mode, type:
p4sandbox -C UTF32 init
You must specify this mode during the initial P4Sandbox creation; you cannot retroactively reconfigure a P4Sandbox to operate in Unicode mode.
For more information on specifying character sets, see the P4CHARSET command in the Perforce Command Reference.
For more information on .p4config files, see the following:
P4CONFIG in the Perforce Command Reference
P4 User's Guide, "Configuring P4," Using Config Files
p4 integrate
Synopsis
Integrate files from a source to a target; automatically create target streams, when necessary.
Syntax
p4 integrate [options] fromFile[revRange] toFile
p4 integrate [options]-S stream [-r] [-P parent] [file[revRange] ...]
Description
p4 integrate (p4 integ) creates the stream for the target when necessary, and then switches the workspace to the target stream.
In the case where the source is a path in a remote depot (that is, a shared service), p4 integrate defines a mapping from the remote depot path to a corresponding location in a mirror stream in the P4Sandbox. The target must be a path into a new or existing mirror stream.
For complete command documentation that includes global options and flags, see the Perforce Command Reference for this command and also p4 resolve. See also Connected P4Sandbox copy restrictions in the Overview.
Options
fromFile[revRange] toFile
See the comprehensive description for these arguments in the Perforce Command Reference for p4 integrate.
-S stream [-r]-P parent [file[revRange] ...]
P4Sandbox automatically switches your workspace to the destination stream before integrating. If the target is a mirror stream, P4Sandbox automatically switches your workspace back to the source stream.
Usage Notes
You can use either p4 integ or p4 stream to create new streams (such as task streams) for your P4Sandbox. We strongly recommend using p4 integ as this command automatically handles more of the stream creation work for you.
A message appears during the initial integration process when there are file case conflict issues. Note that the message does not appear for subsequent integrations.
Related Commands
p4sandbox list
Synopsis
Show all defined P4Sandboxes.
Syntax
p4sandbox list [ -a | all ]
Description
p4sandbox list with no defined options displays all valid existing P4Sandboxes, excluding any that you have deleted or moved.
p4sandbox list -a or all lists all P4Sandboxes that you created, whether they are valid (currently existing) or invalid (deleted or moved).
Options
Display all P4Sandboxes listed in the p4sandbox-list file, regardless of their validity.
Related Commands
Related Commands
p4 merge
Synopsis
Merge changes between streams.
Syntax
p4 merge [options] fromFile[revRange] toFile
p4 merge [options] -S stream [-P parent] [-F] [-r] [toFile[revRange] ...]
Description
p4 merge creates the stream for the target when necessary, and then switches your workspace to the target stream.
If the source is a path in a remote depot (meaning, a shared service path), p4 merge defines a mapping from the remote depot path to a corresponding location in a mirror stream in the P4Sandbox. The target must be a path into a new or existing mirror stream.
If the shared service depot is a streams depot, P4Sandbox maps the entire source stream to the mirror stream and automatically updates this mirror stream mapping during each p4 pull.
Options
fromFile[revRange] toFile
See the comprehensive description for these arguments in the Perforce Command Reference for p4 integrate.
-S stream [-r]-P parent [file[revRange] ...]
P4Sandbox automatically switches your workspace to the destination stream before integrating. If the target is a mirror stream, P4Sandbox automatically switches your workspace back to the source stream.
P4Sandbox automatically switches to the destination stream before merging.
For complete command documentation that includes global options and flags, see the Perforce Command Reference for this command and also p4 resolve. See also Connected P4Sandbox copy restrictions in the Overview.
Related Commands
p4 mergedown
Synopsis
Merge changes from a parent stream to a valid child stream.
Syntax
p4 mergedown
Description
p4 mergedown merges unintegrated changes from the current stream's parent stream to the current stream.
p4 mergedown internally uses p4 resolve -am to resolve conflicts, and then submits the files. If p4 mergedown encounters a conflict it cannot resolve, it stops operating on that particular issue and continues to the next conflict. You must manually resolve all remaining pending conflicts and submit them to complete the merge.
p4 mergedown integrates with the P4Sandbox shelving functionality to handle similar and dissimilar pending changelists. When you shelve a pending changelist to the mirror stream, this also shelves the pending changelist to the shared service. However, when another user submits or deletes the shelved pending changelist on the shared service, one of the following behaviors happens when you next merge down changes:
If the other user does not modify the pending changelist on the shared service, p4 mergedown performs the appropriate action (submit or delete) to the corresponding pending changelist in the mirror stream.
If the other user does modify the pending changelist on the shared service (for example, by adding files), p4 mergedown does not perform any action to the pending changelist in the mirror stream, because the changelists are now dissimilar.
Options
None
Related Commands
p4 populate
Synopsis
Branch a set of files as a one-step operation.
Syntax
p4 populate [options] fromFile[revRange] toFile
p4 populate [options] -S stream [-P parent] [-F] [-r] [toFile[rev] ...]
Description
For complete command documentation that includes global options and flags, see the Perforce Command Reference, p4 populate. See also Connected P4Sandbox copy restrictions in the Overview.
Options
fromFile[revRange] toFile
See the comprehensive description for these arguments in the Perforce Command Reference for p4 integrate.
-S stream [-r]-P parent [file[revRange] ...]
P4Sandbox automatically switches your workspace to the destination stream before integrating. If the target is a mirror stream, P4Sandbox automatically switches your workspace back to the source stream.
Related Commands
To integrate files from a source to a target and automatically create target streams
p4 pull
Synopsis
Update a mirror stream with recent changes from a shared service.
Syntax
p4 pull
p4 pull stream
p4 pull -a
Description
p4 pull copies recent changes from a shared service to a mirror stream. Note that this command updates only the mirror stream, and not any associated (child) local streams.
p4 pull without any arguments updates the associated (parent) mirror stream of the current stream.
Requires a network connection to a shared service.
For complete command documentation about Perforce replica servers and their use of p4 pull, see the Perforce Command Reference, p4 pull.
Options
Related Commands
p4 remote
Synopsis
Create a remote depot to and P4Sandbox clients on a shared repository.
Syntax
p4 remote [-u user] [-B remote-depot-name] -p p4port
p4 remote -d -B remote-depot-name
Description
p4 remote performs the following functions:
Creates an inalterable client specification on the shared repository to enable data exchange between the local P4Sandbox and the shared repository.
A P4Sandbox client specification follows the format:
p4sandbox-<user>-<host><seq>
<user> is the P4USER (or -u) value.
<host> is the client's hostname.
<seq> is an optional numeric string appended to provide uniqueness, if required. (In specific cases of very long client names, P4Sandbox may truncate the trailing right-side end to provide room for the numeric string.)
After you create a remote depot connection, issue the following command to create a mirror stream:
p4 merge //remote/<remote depot path>/... //streams/mirror/...
Options
Specifies the $P4PORT of the shared service, and is required when you create a remote depot connection.
Specify the user account to use when connecting to a shared service. If omitted, the current user is used. Cannot differ from user specified in any previous remote depot.
Note that you cannot delete a used remote depot. A remote depot is considered used if you have used it as a source with any of the following commands:
Requires the -B specification.
Usage Notes
Client specifications that begin with p4sandbox- must not be altered in any way (either the name or contents), or P4Sandbox will be unable to communicate properly with the shared repository. Administrators must ensure that all new and existing form trigger scripts that run on shared services do not affect P4Sandbox clients.
Related Commands
p4 remotes
Synopsis
List all connections to shared services.
Syntax
p4 remotes
Description
p4 remotes displays the remote depot name, $P4PORT, user, client and branch name for each remote connection.
If a remote connection is used by multiple branches, P4Sandbox generates one separate output line for each branch.
Options
None
Related Commands
p4 shelve
Synopsis
Store files from a pending changelist in the depot, without submitting them. When issued on a mirror stream, p4 shelve shelves files to the shared service.
Syntax
p4 shelve [files]
p4 shelve -i [-f | -r]
p4 shelve -r -c changelist#
p4 shelve -c changelist# [-f] [file ...]
p4 shelve -d -c changelist# [-f] [file ...]
Description
When you create, update, or delete a shelf in a mirror stream, P4Sandbox performs the same action to the shelf on the shared service. This functionality enables you to push changes up to the shared service for team review and testing without having to first commit the changes to a stream.
The shelf P4Sandbox creates on the mirror stream contains the associated shelved pending change on the shared service, because P4Sandbox stores the changelist number of the shared service shelf in the description of the mirror shelf. The P4Sandbox checks incoming content changes and removes shelved content that no longer contains differences. If the shelf becomes empty, P4Sandbox deletes it and the corresponding shared service shelf.
For complete command documentation that includes global options and flags, see the Perforce Command Reference for p4 shelve and the related command p4 unshelve.
Related Commands
p4sandbox start
Synopsis
Start one or all previously configured P4Sandbox servers.
Syntax
p4sandbox start all
p4sandbox start [-r p4dDir] [-q]
Description
p4sandbox start all starts all defined P4Sandbox servers.
This form of the command takes no options.
p4sandbox start starts one P4Sandbox.
Options
Default is .p4sandbox.
Usage Notes
If you do not specify options, p4sandbox start searches for a previously configured and idle P4Sandbox, either in the current directory or the nearest ancestor directory, and starts it.
If you implement multiple sandboxes, p4sandbox start searches for a P4Sandbox in the current directory.
Related Commands
p4sandbox stop
Synopsis
Stop one or all P4Sandboxes, whether they are connected to an active TCP connection or not.
Syntax
p4sandbox stop all
p4sandbox stop [-r p4dDir]
Description
p4sandbox stop all stops all defined P4Sandbox servers. This form of the command takes no options.
p4sandbox stop stops one P4Sandbox server.
Options
Default is .p4sandbox.
Usage Notes
p4sandbox stop has the same effect as p4 admin stop because a user is an administrator of his or her P4Sandbox. However, p4sandbox stop does not require a TCP connection to the P4Sandbox.
If you do not specify options, p4sandbox stop searches for a previously configured and running P4Sandbox, either in the current directory or the nearest ancestor directory, and stops it.
Related Commands
p4 submit
Synopsis
Submit changes to a mirror stream; P4Sandbox automatically submits the same changes to the shared service.
Syntax
p4 submit
Description
p4 submit automatically propagates changes from a mirror stream to its defined shared service, using the same submit description as provided for the mirror stream.
The submit to the shared service also includes changelists for fixes to jobs that meet the following conditions:
For complete command documentation, see the Perforce Command Reference, p4 submit.
Related Commands
p4 switch
Synopsis
Display current stream name, or switch stream and automatically perform related actions.
Syntax
p4 switch
p4 switch [-f] name
Description
p4 switch displays the current stream name.
Adding the name argument to this command activates the following behavior:
Unshelves any changes shelved by a previous p4 switch out of the target stream.
Options
Related Commands
Comparing Git and P4Sandbox commands
This section is provided to aid Git users who are working with P4Sandbox.
This section contains the following tables:
Command and concept equivalencies
The table below shows the corresponding P4Sandbox command or concept for a given Git command or concept.
Task equivalencies
The table below contains the following columns:
Git Command: Shows a command or command sequence for the corresponding Git task. This column appears in alphabetical order by command.
Git Task: Shows a task from the Git perspective; note that the actual task and result in P4Sandbox may be slightly different. Be sure to refer to the Command and Concept Equivalencies table above while reading this column.
For example, the Git task List branches in repository is actually List streams in P4Sandbox in P4Sandbox.
P4Sandbox Equivalent: Shows the applicable P4Sandbox command or command sequence.
The table below lists commands for performing the following types of tasks:
Because of table formatting limitations, certain single-line commands are truncated. These commands appear with an indented second line.
 
Stop local repository before computer shutdown2
git branch
git branch
git branch -d branch
p4 copy //streams/parent/... //streams/branch/...
p4 switch branch4
Create a connection to remote repository and perform initial copy
p4 remote -p perforce:1666
p4 copy //remote/depot/main/... //streams/mirror/...
p4 changes dir/...
p4 files dir/...
p4 files //streams/local/...
git merge5 branch
Copy up changes to a local repository that results in no conflicts
git merge branch
vi conflicting_files
git add conflicting_files
Copy up changes to a local repository that results in conflicts
git merge parent_branch
Merge down changes to a local repository that requires no changes to branched files
git merge parent_branch
Merge down changes to a local repository that results in no conflicts
git merge parent_branch
vi conflicting_files
git add conflicting_files
Merge down changes to a local repository that results in conflicts
git pull5 origin master
Merge down changes from a remote repository that results in no changes to branched files
Merge down changes from a remote repository that results in no conflicts
vi conflicting_files
git add conflicting_files
Merge down changes from a remote repository that results in resolving conflicts
Copy up changes from a remote repository that results in no conflicts
vi conflicting_files
git add conflicting_files
Copy up changes from a remote repository that results in resolving conflicts in a development branch
p4 merge -rS8 //streams/branch
p4 switch branch4
p4 unshelve -s change_num
p4 shelve -d -c change_num
p4 change -d change_num

1
Git does not require a command to start or stop a local repository.

2
You are not required to stop a P4Sandbox before shutting down the computer. The normal operating system shutdown will cleanly stop it.

3
Deleting a branch outright is not supported, as Perforce always retains a branch's history. It is possible, however, by using p4 obliterate and p4 change -d; for more information on using these commands, see the Perforce Command Reference.

4
Note that the syntax example is p4 switch name; p4 switch branch and p4 switch name are equivalent commands.

5
In Git, you use different commands to transmit changes to a repository, depending on whether the repository type is local (git merge) or remote (git push and git pull). In P4Sandbox, you use the same commands (p4 mergedown, p4 copyup) to transmit changes to a repository, regardless of the repository type.

6
The initial copy attempt results in conflicts. You must merge, resolve, and submit the conflicts in the local stream before attempting to copy up files again to the mirror stream. If the second copy up attempt is successful, perform a submit.

7
The initial copy attempt results in conflicts. You must merge, resolve, and submit the conflicts in the local stream before attempting to copy up files again to the mirror stream. If the second copy up attempt is successful, perform a submit.

8
Note that p4 copy and p4 merge can take options, while p4 copyup and p4 mergedown cannot.

9
This command invokes a text editor window and displays a changelist. Enter a changelist description to complete this command.

Client mode dependent commands
Git leaves files writable in your system, ready to modify. Perforce usually leaves files read-only and requires p4 edit before modification. To switch Perforce to leave files writable and no longer require p4 edit, set your workspace to allwrite. Run p4 status or p4 reconcile when you are ready to stage files for submit.
The table below lists Git commands for file administration and management tasks in alphabetical order, with the corresponding Perforce command. The appropriate Perforce command depends on your implementation's defined client mode. Note that if you set your Perforce workspace to allwrite, you only need to issue commands when you submit changes or move or rename a file.
Add new file hierarchy
p4 move src dest
p4 move src dest
See also
For more information about:
Perforce command syntax, see the Perforce Command Reference.
Perforce command usage, see the P4 User's Guide, "Issuing P4 Commands."


Previous Table of Contents Index Next

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