Triggering on pushes and fetches

To configure Helix 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.

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 may not 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 Helix 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 Helix 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 Helix 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.