p4 pull

Synopsis

Retrieve metadata or versioned files from a Perforce master server to a replicate, or display status information about pending transfers.

Syntax


p4 [g-opts] pull [-J prefix] [-i interval] [-b interval] [-T excluded_tables] [-P serverid]
p4 [g-opts] pull -u [-i interval]
p4 [g-opts] pull -l [-s | -j [-J prefix]]
p4 [g-opts] pull -d -f file -r revision
p4 [g-opts] pull -L [-i interval]

Description

The p4 pull command provides five syntax variants:

  • The first variant retrieves journal records from a target server specified by P4TARGET.

  • The second variant retrieves file contents from a target server specified by P4TARGET.

  • The third variant displays information about scheduled file transfers.

  • The fourth variant cancels a scheduled file transfer.

  • The fifth variant 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. You need to use this variant if you are using a standby replica for failover.

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.

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. Some replica servers do not need 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 master server's metadata, and at least one p4 pull (with the -u option) to replicate the server's versioned files.

  • The -i option specifies a polling interval (in seconds) between updates. If -i is not specified, p4 pull runs for one polling interval and then exits.

  • The -b option specifies a wait time after a failed pull attempt. If -b is not specified, p4 pull retries after 60 seconds.

Use the -T option to exclude tables you do not want to replicate. For example a build farm server does not need to replicate the db.have, db.working, or db.resolve tables.

To delete a pending file transfer operation, use p4 pull -d -f file -r rev. This can be useful if a pending file transfer is failing repeatedly due to unrecoverable errors on the master.

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 may 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

If -j is specified with -l, report the current journal state at the current replica and its 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.

-d -f file -r rev

Cancel a pending file content transfer, where file and rev refer to a depot file and a specific revision.

Note

This is not the normal Perforce 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.

-i interval

Specify a polling interval in seconds for content retrieval. The smallest interval is one second. If you omit this option, the command runs once and exits.

If you set the interval to be 0, the master server advises the replicate as soon as new data becomes available. This way the replicated server can pull new data with no delay.

-J prefix

Specify a prefix for the journal file; overrides journalPrefix configurable.

If your master server uses a non-default journal location, this allows you to specify the journal file location on the master server.

-l

List files that are scheduled for transfer.

-l -j

Display the current journal state on the replica and the master.

During the process of journal rotation on the master, the output of p4 pull -l -j can have three lines of output: one for the replica journal's current state, one for the state of the corresponding journal on the master, and a third line for the new journal on the master, data from which has not yet arrived at the replica.

-l -s

Display a summary of scheduled file content transfers. If this list is unexpectedly long or is growing, you might consider running additional p4 pull -u commands.

-L

Retrieve journal records from a local journal file, normally produced by the p4 journalcopy command.

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

Note

For compatibility with earlier releases of Perforce, you can also supply filter patterns directly within this field by using the same syntax used by the p4 export, but specifying a server and using fields in the p4 server form is strongly encouraged, because the behavior of a replica that makes use of multiple p4 pull commands with inconsistent or conflicting -P filterpattern arguments is undefined.

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

-u

Transfer archive files instead of journal records. If you omit this option, the command retrieves journal records.

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

  • In most situations, server replication with p4 pull is preferable to p4 replicate.

  • When you stop either the master server or a replica server, the replica server 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.

  • For more about configuring Perforce to run in a replicated environment, see Perforce Server Administrator's Guide: Multi-site Deployment.

Related Commands

To configure a Perforce 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