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.
You might want to take into consideration 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. Files are unlocked even if they were manually locked prior to
submit if submit fails when submit.unlocklocked
is set.
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.
The following table describes the fields of a submit trigger. For sample definitions, see the subsequent sections, describing each trigger subtype.
Field | Meaning |
---|---|
|
The name of the submit trigger. |
|
When using
For example, to submit a file p4 diff2 //depot/foo@1000 file@=1001 p4 diff2 //depot/foo#25 file@=1001 |
|
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
|
|
The trigger for Helix Server
to run when a user submits a changelist that contains any file
patterns specified by 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
For |
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. (That is, a change-submit
trigger fires, a
change-content
trigger fires, but a
change-commit
trigger does not.)