Helix Core P4 Command Reference (2019.1)

p4 sync

Update the client workspace to reflect the contents of the depot.

Syntax

p4 [g-opts] sync [-f -k -L -n -N -q -r] [-m max] [[FileSpec][revSpec]]
p4 [g-opts] sync [-L -n -N -q -s] [-m max] [[FileSpec][revSpec]]
p4 [g-opts] sync [-L -n -N -p -q] [-m max] --parallel=threads=n[,batch=n][,batchsize=n][,min=n][,minsize=n [[FileSpec][revSpec]]  

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 if it meets all three criteria:

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. See File specifications on "Using revision ranges", and p4 archive "Usage Notes", and p4 help revisions.

The p4 sync command gets the latest version from the depot and updates your local workspace files . However, to protect the person working in the local workspace from accidentally losing work, any files that are open in the local workspace when you run p4 sync need to be manually resolved using the p4 resolve command before submitting.

  • Newly synced files are read-only
  • p4 edit and p4 delete make the files writable
Important

To make files writable, use Helix Core server commands. Do NOT use operating system commands.

Note

For users of Helix Server for Distributed Versioning, when specifying file paths, you can use the global changelist ID from the submitted change spec instead of the actual change number. For example:

p4 sync //depot/[email protected]

For more information, see the Using Helix Core Server for Distributed Versioning topic on global changelist IDs, "Track a changelist’s identity from server to server".

Options

-f

Force the sync. Helix server 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 noclobber client option (see p4 client).

-k

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 zerosyncPrefix configurable, all workspaces with names that begin with the specified prefix assume p4 sync -k.

-L

For scripting purposes, perform the sync on a list of valid file arguments in full depot syntax with a valid revision number.

When this flag is used, the arguments are processed together by building an internal table similar to a label. This file list processing is significantly faster than having to call the internal query engine for each individual file argument. However, the file argument syntax is strict and the command will not run if an error is encountered.

-m max

Sync only the first max files specified.

-n

Preview mode: Display the results of the sync without actually performing the sync.

-N

Preview mode: 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 have inadvertently included a folder tree that holds several gigabytes of assets before attempting to sync your newly-configured workspace.

-p

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.

Note

If you are at a replica, and syncing from the replica's depot to your replica workspace, the sync command will fail if the master is not available. This is because the replica needs to be able to update the db.have table on the master. However, in this case, you can use p4 sync -p

--parallel

Specify options for parallel file transfer. The configuration variable net.parallel.max must be set to a value greater than 1 to enable the --parallel option.

  • threads=n sends files concurrently using n independent network connections. The specified threads grab work in batches.

    There is no default value; a value must be set.

  • batch=n specifies the number of files in a batch.

    Default value is 8.

  • batchsize=n specifies the number of bytes in a batch.

    Default value is 512K.

  • min=n specifies the minimum number of files in a parallel sync. A sync that is too small does not initiate parallel file transfers.

    Default value is 9.

  • minsize=n specifies the minimum number of bytes in a parallel sync. A sync that is too small will not initiate parallel file transfers.

    Default value is 576K.

See Parallel processing.

-q

Quiet operation: suppress normal output messages. Messages describing errors or exceptional conditions are not suppressed.

-r

Reopen files that are mapped to new locations in the depot, in the new location. By default, open workspace files remain associated with the depot files that they were originally opened as.

For example, pending work can be moved to a different stream by running p4 client -f -s followed by p4 sync -r.

-s

Safe sync: Compare the content in your client workspace against what was last synced. If the file was modified outside of the control of Helix server, an error message is displayed and the file is not overwritten.

If your client workspace specification has both the allwrite and noclobber options set, this check is performed by default.

g-opts

See Global options.

Usage Notes

Can File Arguments Use Revision Specifier? Can File Arguments Use Revision Range? Minimal Access Level Required

Yes

Yes

read

  • 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 Helix server’s control, p4 sync will not normally overwrite those files. However, if the clobber option in the p4 client form has been turned on, 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 the clobber option is set, p4 sync -s will not overwrite files modified outside of Helix server control.

  • A progress indicator is available for p4 sync if you request it with p4 -I sync -q.
  • Do NOT issue a p4 sync with multiple arguments referencing the same file. For example: p4 sync depot/project/[email protected] //depot/project/[email protected] will result in unpredictable, inconsistent revisions.

Scripting

The -m max option is useful when combined with the -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 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. Parallel processing is most effective:

  • with long-haul, high latency networks
  • if the network configuration prevents making full use of the available bandwidth with a single TCP flow
  • when working with large, compressed binary files, where the client must perform substantial work to decompress the file

Do one of the following:

  • Enable automatic parallel sync by setting both net.parallel.threads and net.parallel.max.
    • For example, if you configure net.parallel.max=40 and net.parallel.threads=3, the p4 sync command automatically uses 3 threads.
  • Manually invoke parallel sync by not setting net.parallel.threads, setting net.parallel.max to a value greater than 1, and using the --parallel option to the p4 sync command.
    • For example, if net.parallel.threads is unset, and net.parallel.max=40, the number of parallel threads can be anywhere within the range of 2 to 40. To run 12 threads in parallel, type at the command line
      p4 sync --parallel=threads=12.
    Note
    • 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.
    • If net.parallel.max=40, that value of net.parallel.threads should be less than or equal to 40. If the requested number of parallel threads exceeds the value set for net.parallel.max, only the maximum number of allowed threads run.
  • The --parallel option allows you to specify how the parallel processing occurs.

    • Use the min and/or minsize suboptions to indicate that you don’t want parallel processing unless the sync involves sending at least min number of files, or at least minsize number of bytes.
    • Use the batch and/or batchsize 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, but at the risk of overloading database resources.

    You can specify the suboptions in any order.

You can also control parallel processing behavior by using:

Working with streams

If both of the following are true:

  • the Stream: field in your client workspace is set to a valid stream
  • the StreamAtChange: field points to a specific changelist number

the command, p4 sync, syncs your workspace to the revisions of files available as of that changelist.

Retrying the command

Over unreliable networks, you can specify the number of retries to attempt and the length of time beyond which the Helix server 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 n, where n is the number of times to attempt reconnection.

The command below 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.

$ p4 -r3 -vnet.maxwait=60 sync

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 file.c to the client workspace, with the same exceptions as in the example above.

p4 sync //depot/proj1/[email protected]

Copy all the files under the //depot/proj1 directory from the depot to the client workspace, as mapped through the client view.

Don’t copy the latest revision; use the revision of the file in the depot after changelist 21 was submitted.

p4 sync @labelname

If labelname is a label created with p4 label, and populated with p4 labelsync, bring the workspace into sync with the files and revision levels specified in labelname.

Files listed in labelname, but not in the workspace view, are not copied into the workspace.

Files not listed in labelname are deleted from the workspace. (That is, @labelname is assumed to apply to all revisions up to, and including, the revisions specified in labelname. This includes the nonexistent revision of the unlisted files.)

p4 sync @labelname,@labelname

Bring the workspace into sync with a label as with p4 sync @labelname, but preserve non-labeled files in the workspace.

(The revision range @labelname,@labelname applies only to the revisions specified in the label name itself, and excludes the nonexistent revision of the unlisted files.)

p4 sync @2018/06/24

Bring the workspace into sync with the depot as of midnight, June 24, 2018. (That is, include all changes made during June 23.)

p4 sync status%40june1st.txt

Sync a filename containing a Helix server wildcard by using the ASCII expression of the character’s hexadecimal value. In this case, the file in the client workspace is [email protected].

For details, see Limitations on characters in filenames and entities.

p4 sync file.c#none

or

p4 sync file.c#0

Sync to the nonexistent revision of file.c so that the file is deleted from the workspace.

p4 sync ...#none

or

p4 sync ...#0

Sync to the nonexistent revision of all files so that all files in the workspace (that are under Helix server control) are removed.

Related Commands

To open a file in a client workspace and list it in a changelist

p4 add
p4 edit
p4 delete
p4 integrate

To copy changes to files in the client workspace to the depot

p4 submit

To view a list of files and revisions that have been synced to the client workspace

p4 have