Helix Core is now P4. Product user interfaces will be updated soon. Learn more >>

P4 CLI Documentation | 2025.2

# p4 sync

Update the client workspace Directories on your machine where you work on file revisions that are managed by P4 Server. to reflect the contents of the depot A file repository hosted on the P4 Server. A depot is the top-level unit of storage for versioned files, which are also known as depot files, archive files, or source files. It contains all versions of all files ever submitted to the depot. Except for obliterated files, any version of any file can be restored, including deleted files, but not obliterated files. An installation can have multiple depots, and they might be of different types, such as a local depot and a stream depot..

## Syntax

    p4 [g-opts] sync [-E -f -L -n -N -k -K -q -r] [-m max]
                     [--parallel=threads=N[,batch=N][,batchsize=N][,min=N][,minsize=N]]
                     [--use-stream-change=N] [file[revRange] ...]
    p4 [g-opts] sync [-E -L -n -N -K -q -s] [-m max] [--use-stream-change=N]
                     [--parallel=threads=N[,batch=N][,batchsize=N][,min=N][,minsize=N]]
                     [file[revRange] ...]
    p4 [g-opts] sync [-E -L -n -N -K -p -q] [-m max] [--use-stream-change=N]
                     [--parallel=threads=N[,batch=N][,batchsize=N][,min=N][,minsize=N]]
                     [file[revRange] ...]
    p4 g-opts sync -k --sync-time=N [files ...]

Syntax and naming conventions

## 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:

- Visible through the client view.
- Not already opened by `p4 edit`, `p4 delete`, `p4 add`, or `p4 integrate`.
- Does not already exist in the client workspace at its latest revision, that is, 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. 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.

To make files writable, use P4 Server commands. Do NOT use operating system commands.

### Delete files quickly from the local client workspace

To quickly and safely delete local workspace files, see the p4 sync ...#none example. This operation is an exception to the general rule that sync'ing is about updating the client workspace to reflect the contents of the depot.

### Parallel syncs

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.

All parallel processing on the server is regulated using the `net.parallel.max` configurable:

- To disable parallel processing, set to 0 or 1

- To enable parallel processing and specify the maximum number of concurrent threads for a single p4 sync, p4 shelve, or p4 submit command, set a value between 2 and 100. Configuration or command line options that request a greater number of parallel threads than the value of net.parallel.max remain limited to the net.parallel.max value.

Too many threads can degrade performance.

#### Manual parallel sync

To enable a manual parallel sync, set the `net.parallel.max` configurable and use the `--parallel` option to the `p4 sync` command. For example, if `net.parallel.threads` is unset and `net.parallel.max=8`, the number of parallel threads can be anywhere within the range of `2` to `8`. This command specifies six parallel threads: `p4 sync --parallel=threads=6`

The `--parallel` option allows you to specify how the parallel processing occurs.

- To prevent parallel processing unless the sync involves sending at least `min` number of files, and at least `minsize` number of bytes, use the `min` and `minsize` suboptions.
- To specify how many files or bytes to transfer at a time, use the `batch` and `batchsize` suboptions . Setting a small batch size might result in the best use of the network, but at the risk of overloading database resources with frequent batches.

#### Automatic parallel sync

To enable automatic parallel syncs, set both the `net.parallel.threads` and `net.parallel.max` configurables. For example, if you configure `net.parallel.max=8` and `net.parallel.threads=3`, the `p4 sync` command automatically uses 3 threads.

Default values and configurables that affect parallel sync operations:

Configurable | Value | Description
--- | --- | ---
net.parallel.batch | 8 | The number of files in a batch.
net.parallel.batchsize | 512 K | The number of bytes in a batch.
net.parallel.min | 9 | The mininum number of files in a batch.
net.parallel.minsize | 576 K | The minimum of bytes in a parallel sync.
net.parallel.sync.svrthreads | 0 | Server-wide parallel sync transmit thread limit.
client.sendq.dir | unset | The directory that will contain a separate db.sendq table for each client.

To learn more, see See Parallel processing for submits, syncs, and shelves in the P4 Server Administration Documentation.

### Performance for large binary files

You might be able to boost performance for the p4 sync command. To learn more, see Delta Transfer of large binary files in the P4 Server Administration Documentation.

### For DVCS

For users of P4 Server for Distributed Versioning (DVCS), 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/...@30E7C829-08C504-4109-89AA-904D0C2194B8

To learn more, see the P4 Server Administration Documentation topic on global changelist IDs, "Track a changelist’s identity from server to server".

### 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.

### 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 P4 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.

This command attempts to sync the user’s workspace, making up to three attempts to resume the sync if interrupted:

    p4 -r3 -vnet.maxwait=60 sync

The command fails after the third 60-second timeout.

Avoid the use of `-r` on any command that reads from standard input. The format of the output of a command that times out and is restarted cannot be guaranteed. For example, network connectivity might break in the middle of a line of output.

### Background transfer from edge to commit

A `p4 sync` command that is running on a commit server for a file revision that was submitted from an edge server might return a librarian A subsystem of the server that stores, manages, and provides the archive files to other subsystems of the server. See also 'archive files'. error message. This can occur if the background file transfer from the edge to the commit has not yet completed. To make the sync operation on the commit server wait for the file transfer to be completed, set the submit.allowbgtransfer configurable:

`p4 configure set commit-server-ID#submit.allowbgtransfer=1`

## Options

Option | Description
--- | ---
`-f` | Force the sync. P4 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).
`-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.
`-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 there are many large files, limits on bandwidth, or limits on disk space. 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.
`-k` | Update server metadata without syncing files. It is intended to enable you to ensure that the server correctly reflects the state of files in the workspace while avoiding a large data transfer. An erroneous update can cause the server to incorrectly reflect the state of the workspace. Keep existing workspace files and update the have list The list of file revisions most recently synced from the depot into the workspace. In other words, the list of files that the client workspace has. 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 `p4 flush`. For additional details and use cases, see p4 flush. If your administrator has set the `zerosyncPrefix` configurable, all workspaces with names that begin with the specified prefix assume `p4 sync -k`.
`-K` | Suppress keyword expansion when updating `+k` type files on the client. To learn more, see File type modifiers.
`-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. If you are at a replica, and syncing from the replica's depot to your replica workspace, the sync command will fail if the target server The immediately upstream server for replica servers, edge servers, standby servers, proxies and brokers. See also 'upstream server' and 'central server'. is not available. This is because the replica needs to be able to update the db.have table on the target server. However, in this case, you can use p4 sync -p
`-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 P4 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.
`-m max` | Sync only the first `max` files specified. This option is useful in conjunction with tagged output and the `-n` flag, to preview how many files will be synced without transferring all the file data.
`-E` | For edge servers replicating from a commit or an upstream edge: Verify that any changelists specified in the [revSpec] are submitted before continuing with the sync. A message reports which changelist numbers, if any, are pending or invalid. If the user of the edge is willing to wait for any changes that are in transit to be replicated to the edge, include the `@now` datespec. For example, `p4 sync -E //depot/project1/...@now` The wait time depends on network performance and the size of any archive files Versioned files that users submitted to a depot. being transferred. (The `@now` datespec is explained in the file@datespec section of Revision specifiers.)
`--parallel` | Specify options for parallel file transfer. The configurable `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 number of threads grab work in batches. There is no default value. suboptions: 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 with fewer files 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 does not initiate parallel file transfers. Default value is `576K`. See Parallel syncs.
`--use-stream-change` | Specify the stream specification version to use for generating the client view for sync. If `–-use-stream-change` is used, the effect is the same as if the dm.sync.streamchange configurable is set to `0`.
Maximum change number in the filelist
If the dm.sync.streamchange configurable is set to `1`, it is as if the `--use-stream-change` were included but not set to a value. This means that the maximum change number in the filelist determines the stream spec version. For example, if the stream specification was changed both in changelist `4` and `7` and you specify `p4 sync fileA fileB@6 fileC@7`, the stream spec version at change `7` is used to generate the client view.
Similarly, if the `–-use-stream-change` is explicitly included but not set to a value, the maximum change number in the filelist determines the stream spec version. For example, if the stream specification was changed both in changelists `4` and `7` and you specify `p4 sync --use-stream-change fileA fileB@6 fileC@7`, the stream spec version at change `7` is used to generate the client view.
Current stream spec version
If no change number is specified on any file in the filelist, the current stream spec version is used. For example, if you specify `p4 sync fileA fileB fileC`, the current stream spec version is used to generate the client view.
Similarly, if the `–-use-stream-change` option is set to `0`, the current stream spec version is used to generate the client view. For example, if you specify `p4 sync --use-stream-change=0 fileA fileB fileC`, the current stream spec version is used to generate the client view.
Arbitrary change number
If the `–-use-stream-change` option is set to a change number, the client view is generated from the stream specification version at or before that change. For example, if the stream specification was changed both in changelists `4` and `7` and you specify `p4 sync --use-stream-change=5 fileA fileB@6 fileC@7`, the stream spec version at change `4` is used to generate the client view.
`--sync-time=N` | The value of N can be Unix epoch time or the perforce date time format.
`g-opts` | See Global options.

## Usage Notes

Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required | Command Alias
--- | --- | --- | ---
Yes | Yes | `read` | p4 sync -k is an alias for `p4 flush` `p4 sync -s` is an alias for p4 update

- 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 P4 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 P4 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/...@1000 //depot/project/file.txt@1010`
  would result in unpredictable, inconsistent revisions.

## 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/...@21` | 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 P4 Server wildcard by using the ASCII expression of the character’s hexadecimal value. In this case, the file in the client workspace is `status@june1st.txt`. For details, see Limitations on characters in filenames and entities.
`p4 sync ...#none` or `p4 sync ...#0` | This command: Causes the local client workspace machine to remove the files that are under P4 Server control and Updates the server's have list The list of file revisions most recently synced from the depot into the workspace. In other words, the list of files that the client workspace has. about the local file deletions. This command is fast because it does not transfer files or affect depot files.

## 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`

Your search for returned results