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

P4 Server Administration Documentation | 2025.1

# Triggering on pushes and fetches

p4 push and p4 fetch are commands specific to the Perforce proprietary distributed version control system (DVCS), which is explained at Distributed versioning (DVCS). There is no requirement that any triggers be run at any point in the submission or push process.

To configure P4 Server to run trigger scripts when the `p4 push`, `p4 unzip`, or `p4 fetch` commands are invoked, use push triggers of type `push-submit`, `push-content`, and `push-commit`.

This section describes the triggers that can be used when initiating a push or fetch for Perforce DVCS.

For a description of the triggers that can be used by the server receiving the pushed items or responding to the fetch request, see Additional triggers for push and fetch commands.

## Similarity between p4 submit and p4 push

During a push, the local server acts as the client of the shared server. Therefore, there are similarities between submits and pushes:

- Push actions are atomic: either everything is pushed or nothing is pushed.
- Pushes occur in three distinct phases and different types of push triggers are appropriate for each phase.

The following figure:

- illustrates the similarities between submits and pushes
- illustrates the path of submitted files, via a changelist, from the client, to the local server, and finally, to the shared server
- includes all possible types of triggers and shows the types of triggers that can be run during each phase of these processes.

Change and push triggers

Three phases of submits and pushes:

(1) Send metadata | (2) Send files | (3) Commit
--- | --- | ---
A `change-submit` or `push-submit` trigger causes metadata to be sent, and executes after changelist creation, but before file transfer. | A `change-content` or `push-content` trigger executes after files are sent, but before changes are committed. | A `change-commit` or `push-commit` trigger executes after the changes are committed.
Cannot access file contents. | Can access file contents by using the revision specifier `@=change`, where `change` is the changelist number of the pending changelist that a command such as p4 diff2, p4 files, p4 fstat, or p4 print passed to the script in the `%changelist%` variable. | Cannot revoke the commit.
A trigger might test to see whether the user is allowed to perform the action or whether the file type is allowed. | A trigger might parse the contents of the files and take appropriate action. One possibility is to determine whether the submitted files adhere to coding conventions. | A trigger might send a notification, or do some clean up.

## Differences between p4 submit and p4 push

Differences between submits and pushes:

- While both submits and pushes are atomic
  - a submit encompasses a single changelist
  - push can contain multiple changelists. Thus the failure of a push is more costly.
- Submits are unidirectional.
- Pushes are the result of a `p4 push`, `p4 fetch`, or `p4 unzip` and are bidirectional. Depending on the command that causes the trigger to execute, either the local server or the shared server might play the role of client.
- During the first phase of a push, metadata is read into memory, which limits the data that the `push-commit` trigger can access. Each `push-commit` trigger is a separate process with its own memory. See Push-submit triggers.
- If a submit fails, you’re left with work in progress that you can change and retry. Having a push operation fail requires that you retrace your steps prior to the submit to the local server. For this reason, you might want to run triggers during the submit operation rather than the push operation if possible.
- Change triggers are involved in the processing of `p4 submit` commands only. Push triggers are invoked in the context of three somewhat different scenarios: the execution of `p4 push`, `p4 fetch`, or `p4 unzip` commands.

You should keep these differences in mind when you decide how to define your triggers and at what stage to run them.

## Fields on a p4 push trigger

The following table describes the fields of a push trigger. For sample definitions, see the subsequent sections, describing each push trigger type.

Field | Meaning
--- | ---
`name` | The name of the push trigger.
`type` | push-submit: Execute this trigger after changelist creation, but before file transfer. Trigger cannot access file contents. push-content: Execute this trigger after changelist creation and file transfer, but before file commit. To obtain file contents, use the revision specifier `@=change` (where `change` is the changelist number of the pending changelist as passed to the script in the `%changelist%` variable) with commands such as `p4 diff2`, `p4 files`, `p4 fstat`, and `p4 print`. push-commit: Execute this trigger after changelist creation, file transfer, and changelist commit.
`path` | A file pattern in depot syntax. When a user uses the `p4 push`, `p4 unzip`, or `p4 fetch` commands to submit a changelist that contains any files that match this file pattern, the trigger specified in the `command` field is run. Use exclusionary mappings to prevent triggers from running on specified files.
`command` | The trigger for the P4 Server to run when a user invokes the `p4 push`, `p4 unzip`, or `p4 fetch` commands to submit a changelist that contains any file patterns specified by `path`. Specify the command in a way that allows the P4 Server account to locate and run the command. The `command` (typically a call to a script) must be quoted, and can take as arguments anything that your `command` is capable of parsing, including any applicable P4 Server trigger variables. When your trigger script is stored in the depot, its path must be specified in depot syntax, delimited by percent characters. For example, if your script is stored in the depot as `//depot/scripts/myScript.pl`, the corresponding value for the command field might be `"/usr/bin/perl %//depot/scripts/myScript.pl%"`. See Storing triggers in the depot for more information. For `push-submit` and `push-content` triggers, changelist submission does not continue if the trigger fails. For `push-commit` triggers, changelist submission succeeds regardless of trigger success or failure, but subsequent `push-commit` triggers do not fire if the script fails.

Even when a `push-submit` or `push-content` trigger script succeeds, the submission that caused the trigger to run can fail because of subsequent trigger failures, or for other reasons. Use `push-submit` and `push-content` triggers only for validation, and use `push-commit` triggers for operations that are contingent on the successful completion of the push or fetch.

Your search for returned results