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: these include 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.

The three phases of submits and pushes include the following:

1. Send metadata causes metadata to be sent.

   Following this phase, a change-submit or push-submit trigger may test to see whether the user is allowed to perform the action, whether the file type is acceptable, and so on. Anything one can query about the metadata is actionable.

2. Send files. The Files are sent but changes are not yet committed.

   Following this phase, a content-submit or push-submit trigger may parse the contents of the files and take appropriate action depending on what it discovers. During this phase, one might look to see whether the submitted files adhere to coding conventions or other policies.

3. Commit. The changes are committed.

   Following this phase, the commit is irrevocable, but the trigger may take some action: send a notification, do some clean up, and so on.

Differences between p4 submit and p4 push

Turning to look at the differences between submits and pushes, we discover the following:

• While both submits and pushes are atomic, a submit encompasses a single changelist; a push may contain multiple changelists. Thus the failure of a push is more costly.
• Submits are unidirectional; pushes (which might happen as the result of a p4 push, p4 fetch, or p4 unzip) 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 (which is a separate process with its own per-instance memory) can access. See Push-submit triggers for more information.
• 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
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.