p4 sync
Synopsis
Update the client workspace to reflect the contents of the depot.
Syntax
p4 [g-opts
] sync [-f][-L][-k][-n][-N][-q][-m max
] [file
[revRange
]...]
p4 [g-opts
] sync [-L][-n][-N][-q][-s][-m max
] [file
[revRange
]...]
p4 [g-opts
] sync [-L][-n][-N][-p][-q][-m max
] [file
[revRange
]...]
p4 [g-opts
] sync [-L][-n][-N][-p][-q][-m max
] [file
[revRange
]...]
--parallel=threads=n
[,batch=n
][,batchsize=n
][,min=n
][,minsize=n
]
Description
p4 sync brings the client workspace into sync with the depot by copying files matching its file pattern arguments from the depot to the client workspace. When no file patterns are specified on the command line, p4 sync copies a particular depot file only if it meets all of the following criteria:
-
It is visible through the client view;
-
It is not already opened by p4 edit, p4 delete, p4 add, or p4 integrate;
-
It does not already exist in the client workspace at its latest revision (the head revision).
In new, empty, workspaces, all depot files meet the last two criteria, so all the files visible through the workspace view are copied into the user's workspace.
If file patterns are specified on the command line, only those files that match the file patterns and that meet the above criteria are copied.
If the file pattern contains a revision specifier, the specified revision is copied into the client workspace.
If the file argument includes a revision range, only files included in the revision range are updated, and the highest revision in the range is used. Files that are no longer in the workspace view are not affected if the file argument includes a revision range. Use p4 help revisions to get help about specifying revisions.
The newly synced files are not available for editing until opened with p4 edit or p4 delete. Newly synced files are read-only; p4 edit and p4 delete make the files writable. Do not use your operating system's commands to make the files writable; instead, use Perforce to do this for you.
Options
|
Force the sync. Perforce performs the sync even if the client workspace already has the file at the specified revision. If the file is writable, it is overwritten.
This option does not affect open files, but it
does override the
|
|
Keep existing workspace files; update the have list without updating the client workspace. Use p4 sync -k only when you need to update the have list to match the actual state of the client workspace. p4 sync -k is an alias for the p4 flush. Refer to documentation for the p4 flush for additional details and a description of the relevant use cases.
If your administrator has set the
|
|
For scripting purposes, perform the sync on a list of valid file arguments in full depot syntax with a valid revision number. |
|
Sync only the first |
|
Display the results of the sync without actually performing the sync. This lets you make sure that the sync does what you think it does before you do it. |
|
Display a summary of the expected network traffic associated with a sync, without performing the sync. This tells you how many files are to be added or updated, which is useful if you're dealing with many large files and/or are bandwidth or diskspace-limited. This option is useful for estimating network impact of a sync before attempting to perform the sync. If you've recently updated your client workspace view, it's useful to know if you've inadvertently included a folder tree that holds several gigabytes of assets before attempting to sync your newly-configured workspace. |
|
Populate a client workspace, but do not update the have list. Any file that is already synced or opened is bypassed with a warning message. This option is typically used for workspaces used in processes (such as certain build or publication environments) where there is no need to track the state of the workspace after it has first been synced. |
|
Quiet operation: suppress normal output messages. Messages describing errors or exceptional conditions are not suppressed. |
|
Safe sync: Compare the content in your client workspace against what was last synced. If the file was modified outside of Perforce control, an error message is displayed and the file is not overwritten.
If your client workspace specification has both the
|
|
Specify options for parallel file transfer. The configuration
variable
See Parallel processing below for more information. |
|
See the “Global Options” section. |
Usage Notes
Can File Arguments Use Revision Specifier? |
Can File Arguments Use Revision Range? |
Minimal Access Level Required |
---|---|---|
Yes |
Yes |
|
-
If the client workspace view has changed since the last sync, the next sync removes from the client workspace those files that are no longer visible through the workspace view (unless a revision range is used), and copies into the client workspace those depot files that were not previously visible.
By default, any empty directories in the workspace are cleared of files, but the directories themselves are not deleted. To remove empty directories upon syncing, turn on the
rmdir
option in the p4 client form. -
If a user has made certain files writable by using OS commands outside of Perforce's control, p4 sync will not normally overwrite those files. If the
clobber
option in the p4 client form has been turned on, however, these files will be overwritten.You can prevent this behavior (at a minor cost in performance) by using the
-s
"safe sync" option. Even if theclobber
option is set, p4 sync -s will not overwrite files modified outside of Perforce control. -
A progress indicator is available for p4 sync if you request it with p4 -I sync -q.
Scripting
The -m
option is useful
when combined with the max
-n
option for efficient
scripting. For example, a command like p4 sync -n -m
1 does not sync any files, but displays only one line of
output if there are any files to be synced, or a message indicating that
the workspace is up to date. Without the -m 1
option,
the output could conceivably be thousands of lines long, all of which
would be discarded.
The -L
option is intended for use by scripts or
automated reporting processes. File arguments must be in full depot
syntax, and have a valid revision number. File specifications that do
not meet these requirements are silently ignored. Using this option
speeds up file list processing.
Parallel processing
Depending on the number of files being transferred, the p4
sync command might take a long time to execute. You can speed
up processing by having this command transfer files using multiple
threads. You do this by setting the net.parallel.max
configuration variable to a value greater than one and by using the
--parallel
option to the p4 sync
command. Parallel processing is most effective with long-haul, high
latency networks or with other network configuration that prevents the
use of available bandwidth with a single TCP flow. Parallel processing
might also be appropriate when working with large compressed binary
files, where the client must perform substantial work to decompress the
file.
To configure parallel processing, set the
net.parallel.max
configuration variable to a value
greater than one and use the --parallel
option to the
p4 sync command.
-
The
net.parallel.max
configuration variable can be set to any value between 0 and 100. A value of 0 or 1 disables parallel processing. A value greater than 1 enables parallel processing up to the specified level. So if you want to set the--parallel
option to 12, thenet.parallel.max
variable must be set to at least 12. -
The
--parallel
option allows you to specify how the parallel processing is to be done. You can specify the suboptions in any order.Use the
min
and/orminsize
suboptions to indicate that you don't want parallel processing unless the sync involves sending at leastmin
number of files or at leastminsize
number of bytes.Use the
batch
and/orbatchsize
suboptions to specify how many files or bytes should be taken at a time. Setting the batch size small should result in the best use of the network at the risk of overloading database resources.
Working with streams
If your client workspace is dynamically-generated because your client
workspace's Stream:
field is set to a valid stream,
and you have also set the StreamAtChange:
field to
point to a specified changelist number, p4 sync, when
called with no arguments, will sync your workspace to the revisions of
files available as of that changelist, using the client workspace that
corresponds to the corresponding stream specification at that point in
time.
Retrying the command
Over unreliable networks, you can specify the number of retries to
attempt and the length of time beyond which the Perforce application
assumes that the network has timed out. Set
net.maxwait
in your workspace's
P4CONFIG
file or on a
one-command basis from the command line, and specify the number of
retries with -r
, where
n
n
is the number of times to attempt
reconnection. For example, the command:
p4 -r3 -vnet.maxwait=60 sync
attempts to sync the user's workspace, making up to three attempts to resume the sync if interrupted. The command fails after the third 60-second timeout.
Because the format of the output of a command that times out and is
restarted cannot be guaranteed (for example, if network connectivity is
broken in the middle of a line of output), avoid the use of
-r
on any command that reads from standard input.
Examples
p4 sync |
Copy the latest revision of all files from the depot to the client workspace, as mapped through the client view. If the file is already open in the client workspace, or if the latest revision of the file exists in the client workspace, it is not copied. |
p4 sync file.c#4 |
Copy the fourth revision of |
p4 sync //depot/proj1/...@21 |
Copy all the files under the Don't copy the latest revision; use the revision of the file in the depot after changelist 21 was submitted. |
p4 sync
@ |
If
Files listed in
Files not listed in
|
p4 sync
@ |
Bring the workspace into sync with a label as with p4 sync @labelname, but preserve unlabelled files in the workspace.
(The revision range
|
p4 sync @2011/06/24 |
Bring the workspace into sync with the depot as of midnight, June 24, 2011. (That is, include all changes made during June 23.) |
p4 sync status%40june1st.txt |
Sync a filename containing a Perforce wildcard by using the
ASCII expression of the character's hexadecimal value. In this
case, the file in the client workspace is
For details, see Limitations on characters in filenames and entities. |
p4 sync file.c#none |
Sync to the nonexistent revision of |
p4 sync ...#none |
Sync to the nonexistent revision of all files; all files in the workspace (that are under Perforce control) are removed. |