Triggering on submit and populate

To configure Helix Server to run trigger scripts when users submit changelists, use submit triggers: these are triggers of type change-submit, change-content, and change-commit.

You can also use change-failed triggers for the p4 submit or the p4 populate command.

Note

The p4 populate command branches a set of files (the source) into another depot location (the target) in a single step. Therefore, to access the files of a change being submitted by p4 populate, use a change-content trigger (see Change-content triggers) and the p4 files @=change command. (In the case of p4 populate, a change-content trigger is equivalent to a change-submit trigger because no file transfer takes place from the client.)

Change-submit triggers can use the %command% trigger script variable to ignore populate commands (%command% == user-populate) so that change-content triggers can process p4 populate commands.

File locking behavior associated with submits:

Before committing a changelist, p4 submit briefly locks all files being submitted. If any file cannot be locked or submitted, the files are left open in a numbered pending changelist. By default, the files in a failed submit operation are left locked unless the submit.unlocklocked configurable is set. If submit fails when submit.unlocklocked is set, files are unlocked even if they were manually locked prior to submit.

The fields of a submit trigger

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

Field	Meaning
`name`	The name of the submit trigger.
`type`	The event that causes the trigger to fire. change-submit: Execute a submit trigger after changelist creation, but before file transfer. Trigger cannot access file contents. See Change-submit triggers. change-content: Execute a submit 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`. See Change-content triggers. change-commit: Execute a submit trigger after changelist creation, file transfer, and changelist commit. See Change-commit triggers. change-failed: Execute a submit trigger if the `p4 submit` or the `p4 populate` command fails. This trigger only fires on errors that occur after a commit process has started. It does not fire for early usage errors, or due to errors from the submit form. If an edge or change trigger could have run, the `change-failed` trigger will fire if that commit fails. See Change-failed triggers. `edge-submit`: Executes a pre-submit trigger on the edge server after changelist has been created, but prior to file transfer from the client to the edge server. The files are not necessarily locked at this point. See Triggers and commit-edge. `edge-content`: Executes a mid-submit trigger on the edge server after file transfer from the client to the edge server, but prior to file transfer from the edge server to the commit server. At this point, the changelist is shelved. See Triggers and commit-edge. Note When using `p4 diff2` in a `change-content` trigger: The first file argument can be either `file@change` or `file#headrev`, but NOT `file@=change`. The second file argument (typically the change being submitted) must use the `file@=change` syntax to report differences successfully. (Using `file@change` without the equals sign reports the file revisions as identical, which is wrong.) For example, to submit a file `//depot/foo` as change 1001, and the previously submitted change was 1000, with a head revision of 25, both these revision specifier formats should work correctly if generated and called in the trigger script: p4 diff2 //depot/foo@1000 file@=1001
`path`	A file pattern in depot syntax. When a user submits 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 Helix Server to run when a user submits 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 `change-submit` and `change-content` triggers (and their corresponding edge server triggers), changelist submission does not continue if the trigger fails. For `change-commit` triggers, changelist submission succeeds regardless of trigger success or failure, but subsequent `change-commit` triggers do not fire if the script fails.

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

Be aware of edge cases. For example, if a client workspace has the revertunchanged option set, and a user runs p4 submit on a changelist with no changed files, a changelist has been submitted with files contents, but no changes are actually committed. In this case, a change-submit trigger fires, a change-content trigger fires, but a change-commit trigger does not.