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

P4 CLI Reference | 2025.1

# p4 pull

Retrieve metadata or versioned files from a P4 Server target server The immediately upstream server for replica servers, edge servers, standby servers, proxies and brokers. See also 'upstream server' and 'central server'. to its standby or replica, or display status information about pending transfers, although there is a special syntax for a commit server to pull from a replica. In most situations, server replication with `p4 pull` is preferable to `p4 replicate`.

## Syntax for a replica to pull from a commit server

    p4 [g-opts] pull [-J prefix] [-i interval] [-b  -i interval] [-T excluded_tables] [-P serverid]
    p4 [g-opts] pull -u [-i interval -b interval --batch=number --min-size=number  --max-size=number --trigger]
    p4 [g-opts] pull -l [ --filter=failed|active|retry] [-C] [-s] [-v] [-h] | -j [-v] ] [-J prefix] ]
    p4 [g-opts] pull -d -f file -r revision
    p4 [g-opts] pull -L [-i interval]
    p4 [g-opts] pull -R [file]
    p4 pull -T

Syntax conventions

## Syntax for a commit server to pull from a replica

p4 pull -u -t target [-i interval -b interval]

## Description

Except for testing purposes, `p4 pull` is rarely run from the command line. Instead, set the startup.N configurable to start the `p4 pull` processes every time the replica server starts.

The `p4 pull` command provides syntax variants, such as:

- p4 [g-opts] pull [-J prefix] [-i interval] [-b interval] [-T excluded_tables] [-P serverid]
  Retrieves journal records from a target server specified by `P4TARGET`

- p4 [g-opts] pull -u [-i interval -b interval --batch=number --min-size=number --max-size=number --trigger]
  Retrieves file contents from a target server specified by `P4TARGET`

- p4 [g-opts] pull -l [-s | -j [-J prefix]]
  Displays information about scheduled file transfers.

- p4 [g-opts] pull -d -f file -r revision
  Cancels a scheduled file transfer.

- p4 [g-opts] pull -L [-i interval]
  Specifies that journal records be retrieved from a local journal file (produced by the `p4 journalcopy` command) rather than from the journal file of the target server. These records are then written to the replica’s database. For a standby replica for failover.

    p4 [g-opts] pull -R

retries all failed transfers.

    p4 [g-opts] pull -R  file

retries the failed transfer of the specified file.

### The state file

When you stop either the target server or its replica or standby, the replica or standby tracks the most recent journal position in a small text file called the state file. By default, the state file is named `state` and resides in the replica server’s root directory. You can specify a different file name by setting the `statefile` configurable with `p4 configure`.

### Retrieving journal and file content

The `p4 pull` command instructs the current replica server to retrieve either journal records or file contents from a target server specified by `P4TARGET`. A replica server is not required to retrieve both journal records and file contents. For example, if you are creating a replica to help with offline checkpointing, you do not need to transfer file contents.

To replicate both metadata and file contents, you must run at least two `p4 pull` commands:

- One `p4 pull` (without the `-u` option) to replicate the target server’s metadata, and

- At least one `p4 pull` (with the `-u` option) to replicate the server’s versioned files.

Setting the `rpl.compress` configurable allows you to compress journal record data that is transmitted using `p4 pull`.

### Getting status information

Use the `-l` option to display a list of files that are scheduled for transfer. If `-s` is specified along with `-l`, a summary of scheduled file transfers is displayed. An additional line specifies the oldest changelist number that has at least one pending transfer. This provides a clue about how far the replica is lagging in its transfer of archive content.

An operator can run the `p4 journalcopy -l`, `p4 pull -l -j`, and `p4 pull -l -s` commands. This makes it possible for an operator to confirm the state of a replica.

    File transfers: n active/m total, bytes: nnn active/mmmmm total.
    Oldest change with at least one pending file transfer: n

For example, the following output:

    File transfers: 1 active/63 total, bytes: 745 active/23684 total.

Tells us that there are 63 pending archive file transfers, one of which is currently active; and there are 23,684 bytes needed to be transferred of which 745 are currently actively being transferred.

If `-j` is specified with `-l`, report the current journal state at the current replica and its upstream server Any server in the inward direction, that is, toward the central server. For example, in an edge-to-edge configuration with a commit, edge1, and edge2, both edge1 and the commit server are upstream servers for edge2. See also 'central server'. (master), the last time the state file was modified, and the server’s local time and time zone. For example:

    Current replica journal state is: Journal jjj, Sequence: sssss.
    Current master journal state is: Journal jjj, Sequence: sssss.
    The statefile was last modified at: 2012/01/10 14:23:23.
    The Server time is currently: 2012/01/10 14:23:23 -0800 PST

The value of `jjj` specifies a journal number; `sssss` specifies an offset in that journal.

## Options

`-b interval` | Specify a polling interval in seconds for retries after failed retrieval attempts. If you do not specify this option, the pull is retried after 60 seconds. The default of 50 retries can be adjusted with the lbr.retry.max configurable.
`-u` | Transfer archive files Versioned files that users submitted to a depot. instead of journal records. If you omit this option, the command retrieves journal records. Multiple p4 pull -u commands can be active on a single replica server. You might be able to boost performance for the p4 pull -u command. To learn more, see Delta Transfer of large binary files in the P4 Server Administration Documentation.
`--batch number` | Use this option to specify the number of files a pull thread should process in a single request. For high-latency configurations, providing a larger value than the default might improve archive transfer speed for large numbers of small files. Default: `1`
`--min-size number` | The `--min-size` and `--max-size` options: Must be used with the `-u` and --batch Can be used with pull commands that create different pull threads for files with different sizes Pull threads called with these options pull files within the data size range specified with these options. The default size unit is bytes, but K, M, G, and T modifiers can also be used, such as 2K. See Example for min and max sizes.
`--max-size number`
`-d -f file -r revision` | Cancel a pending file content transfer, where `file` and `revision` refer to a depot file and a specific revision. This is not the normal P4 Server file and revision data, but rather the archive file and revision. Use the `p4 pull -l` command to get the correct file name and revision. The archive revision reported by the `p4 pull -l` command typically has a `1.` prefix. For example, the `p4 pull -l` command might report the archive revision as `1.38` for the transfer of revision 38 of a file. Then, to cancel the transfer of revision `38` of the file: `p4 pull -d -f //project1/big.mpeg -r 1.38`
`-i interval` | Interval in seconds for the pull command to query the target server to find out if there is new work to do. Note that the pull command runs continuously until the replica collects all journal data from its target server The immediately upstream server for replica servers, edge servers, standby servers, proxies and brokers. See also 'upstream server' and 'central server'.. Only after the replica has caught up does the interval apply. The smallest interval between queries is 1, which means one second. If you set the interval to `0`, the target server advises the replica as soon as new data becomes available. If you omit this option, the pull command runs only one time and exits.
`-l` | List archive files Versioned files that users submitted to a depot. that are scheduled for transfer. The archive revision reported by the `p4 pull -l` command typically has a `1.` prefix. For example, the `p4 pull -l` command might report the archive revision as `1.38` for the transfer of revision 38 of a file. If you use this option on an edge server or build server that has `lbr.replication=cache` set, you might see several entries because of parallel file transfers. p4 pull -l (and `p4 pull -ls`) can be done on a commit server to monitor reverse replication as a result of submits to edge servers. -l suboptions: -C Purges the records of archive files that are already in place or no longer referenced by the database. This reduces the number of records listed. --filter=failed Display transfer records that failed and won't be retried. --filter=active Display transfer records that are still active. --filter=retry Display transfer records that failed but will be retried. -s Display a summary of pending file transfers. If this list is unexpectedly long or is growing, consider running additional `p4 pull -u` commands. -j Display a summary of pending journal transfers. -v With -lsv, display a summary with separate numbers Active, Queued, Failed , and Retry. This display of the current lag of pending journal transfers does not depend on the setting of the rpl.track.behind configurable. -h With -lsh, display file size numbers in human-readable format.
`-L` | Retrieve journal records from a local journal file, normally produced by the `p4 journalcopy` command.
-J prefix | Specify a file name prefix to match the prefix used with p4d -jc prefix for a rotated journal file. This overrides the `journalPrefix` configurable and can be used when pulling journal records or when listing pending journal transfers. If your target server uses a non-default rotated journal location, this allows you to specify the rotated journal file location on the target server.
`-P serverid` | Filter data from `serverid` according to the `ArchiveDataFilter:` and `ClientDataFilter:` and `RevisionDataFilter` fields in the specified server’s `p4 server` form. In older releases, this option confirmed filters defined in the filter spec. This confirmation is no longer required. The option is retained for continued support of earlier releases. It can also be useful if you want to share filter configuration among multiple servers. In this case, the `serverid` refers to the server whose filter definitions you want shared. For compatibility with earlier releases of P4 Server, you can also supply filter patterns directly within this field by using the same syntax used by the `p4 export`. However, specifying a server and using fields in the `p4 server` form is better because the behavior of a replica that makes use of multiple `p4 pull` commands with inconsistent or conflicting `-P filterpattern` arguments is undefined.
`-R` | p4 pull -R file retries the failed transfer of the specified file. p4 pull -R retries ALL failed transfers. The `-d` option can be used to remove pending or failed file transfers individually, this option will instead reset the retry count of failed transfers so that subsequent pull operations can retry the transfers.
`-T excluded_tables` | Supply a list of database tables (for example, `db.have` and `db.working`) to exclude from the replica’s journal records. The table names must begin with `db.`, following the naming convention used for database files in the server root directory. To specify multiple tables, double-quote the list and separate the table names with spaces. Table names can also be separated by commas. For example, `-T db.have,db.working` or `-T "db.have db.working"`.
`--trigger` | The `--trigger` option is used with a pull-archive trigger to transfer files using an alternative file transfer mechanism from within the trigger. This option is only used in a multi-server environment and is not supported for RCS storage. The configurable pull.trigger.dir must be set to a location to write temporary files. It is also recommended to set the configurable lbr.replica.notransferto `=1` to suppress "on demand" file transfer.
-t target | On the commit server, if p4 pull -l indicates that the commit server is not able to pull the archives from the edge, issue the following command manually: p4 pull -u -t target where: -u enables archive transfer target specifies the ExternalAddress field of the server spec of the edge. (See p4 server)
`g-opts` | See Global options.

## Usage notes

Can File Arguments Use Revision Specifier? | Can File Arguments Use Revision Range? | Minimal Access Level Required
--- | --- | ---
N/A | N/A | `super` the `-lj` and `-ls` options are available to an operator user

For more about configuring P4 Server to run in a replicated environment, see Replication in the P4 Server Administration Documentation.

## Example for min and max sizes

    startup.2=pull -u -i 1  --batch=1000 --min-size=1 --max-size=2047
    startup.3=pull -u -i 1  --batch=5 --min-size=2048 --max-size=4096
    startup.4=pull -u -i 1  --batch=5 --min-size=4097

## Examples with filter

To display records that failed but will be retried:

    p4 pull -l --filter=retry

To display a summary of records that failed:

    p4 pull -l --filter=failed -s

## Related commands

To configure a P4 Server to run a set of `p4 pull` commands upon startup. | `p4 configure`
To replicate metadata from one server to another | `p4 replicate`
To display journal or checkpoint records in raw form | `p4 export`
To copy journal data to a replica’s local file system. | `p4 journalcopy`

Your search for returned results