p4 triggers
Synopsis
Edit a list of scripts to be run conditionally whenever changelists are submitted or forms are updated.
Syntax
p4 [g-opts] triggers
p4 [g-opts] triggers -i
p4 [g-opts] triggers -o
Description
Perforce triggers are user-written scripts that are called by a Perforce server whenever certain operations (such as changelist submission or changes to forms) are performed. If the script returns a value of 0, the operation continues; if the script returns any other value, the operation fails. Upon failure, the script's standard output (not error output) is used as the text of the failed operation's error message.
There are six trigger types. The first three trigger types (submit, content, and commit) are fired when users submit changelists, and are referred to as changelist submission triggers. The remaining trigger types (save, out, and in) are fired when users generate or modify form specifications, and are referred to as specification triggers.
Use the submit trigger type to create triggers that fire after changelist creation, but before files are transferred to the server. Because submit triggers fire before files are transferred to the server, submit triggers cannot access file contents. Submit triggers are useful for integration with reporting tools or systems that do not require access to file contents.
Use the content trigger type to create triggers that fire after changelist creation and file transfer, but prior to committing the submit to the database.
Use the commit trigger type to create triggers that fire after changelist creation, file transfer, and changelist commission to the database. Use commit triggers for processes that assume (or require) the successful submission of a changelist.
To configure Perforce to run trigger scripts when users edit specifications, use specification triggers: these are triggers of type save, in, and out. Use specification triggers to generate customized specifications for users, validate customized specifications, to notify other users of attempted changes to specification forms, and to otherwise interact with process control and management tools.
Triggers are run in the order listed in the table; if a trigger script fails for a specified type, subsequent trigger scripts also associated with that type are not run.
Even when a submit or content trigger script succeeds, the submit may fail because of subsequent trigger failures, or for other reasons. Use submit and content triggers only for validation, and use commit triggers or daemons for operations that are contingent on the successful completion of the submit.
To use the same trigger script with multiple file patterns, list the same trigger multiple times in the trigger table. Use exclusionary mappings to prevent files from activating the trigger script; the order of the trigger entries matters, just as it does when exclusionary mappings are used in views. If a particular trigger name and type is listed multiple times, only the script corresponding to the first use of the trigger name and type is activated.
Form Fields
The p4 triggers form contains a single Triggers: field. Each row in the field holds four values:
Field
|
Meaning
|
|---|
|
name
|
The user-defined name of the trigger.
|
|
type
|
There are six trigger types. The first three trigger types (submit, content, and commit) are fired when users submit changelists, and are referred to as changelist submission triggers. The remaining trigger types (save, out, and in) are fired when users generate or modify form specifications, and are referred to as specification triggers.
- submit: Execute a changelist trigger after changelist creation, but before file transfer. Trigger may not access file contents.
- content: Execute a changelist trigger after changelist creation and file transfer, but before file commit.
- To obtain file contents, use commands such as p4 diff2, p4 files, p4 fstat, and p4 print with the revision specifier @=change, where change is the changelist number of the pending changelist as passed to the script in the %changelist% variable.
- commit: Execute a changelist trigger after changelist creation, file transfer, and changelist commit.
- save: Execute specification trigger after its contents are parsed, but before its contents are stored in the Perforce database. Trigger may not modify form specified in %formfile% variable.
- out: Execute specification trigger upon generation of form to end user. Trigger may modify form.
- in: Execute specification trigger on edited form before contents are parsed and validated by the Perforce server. Trigger may modify form.
|
|
path
|
For changelist submission triggers (submit, content, or commit), a file pattern in depot syntax. When a user submits a changelist that contains any files that match this file pattern, the script linked to this trigger is run. Use exclusionary mappings to prevent triggers from running on specified files.
For specification triggers (save, out, or in), the name of the type of form, such as branch, client, and so on. Triggers that fire on the p4 triggers command are ignored.
|
|
command
|
The command for the Perforce server to run when a matching path applies for the trigger type. Specify the command in a way that allows the Perforce server account to locate and run the command. The command must be quoted, and can take the variables specified below as arguments.
For submit and content triggers, changelist submission continues if the trigger script exits with 0, or fails if the script exits with a nonzero value. For commit triggers, changelist submission succeeds regardless of the trigger script's exit code, but subsequent commit triggers do not fire if the script exits with a nonzero value.
For in, out, and save triggers, the data in the specification becomes part of the Perforce database if the script exits with 0. Otherwise, the database is not updated.
|
Options
|
-i
|
Read the trigger table from standard input without invoking the editor.
|
|
-o
|
Write the trigger table to standard output without invoking the editor.
|
|
g-opts
|
See the Global Options section.
|
Usage Notes
Can File Arguments Use
Revision Specifier?
|
Can File Arguments Use
Revision Range?
|
Minimal Access Level Required
|
|---|
|
N/A
|
N/A
|
super
|
Warning!
|
Never use a Perforce command in an out trigger that fires the same out trigger, or infinite recursion will result. For example, never run p4 job -o from within an out trigger script that fires on job specifications.
|
- To pass arguments to the trigger script, use the following variables:
Argument
|
Description
|
Available for type
|
|---|
|
%changelist%
|
The number of the changelist being submitted. (The abbreviated form %change% is equivalent.)
|
submit, content, and commit
|
|
%client%
|
Triggering user's client workspace name.
|
all
|
|
%clienthost%
|
Hostname of the client.
|
all
|
|
%clientip%
|
The IP address of the client.
|
all
|
|
%serverhost%
|
Hostname of the Perforce server.
|
all
|
|
%serverip%
|
The IP address of the server.
|
all
|
|
%serverport%
|
The IP address and port of the Perforce server, in the format ip_address:port.
|
all
|
|
%serverroot%
|
The P4ROOT directory of the Perforce server.
|
all
|
|
%user%
|
Perforce username of the triggering user.
|
all
|
|
%formfile%
|
Path to temporary specification file. To modify the form from an in or out trigger, overwrite this file. The file is read-only for triggers of type save.
|
save, out, and in
|
|
%formname%
|
Name of form (for instance, a branch name or a changelist number).
|
save, out, and in
|
|
%formtype%
|
Type of form (for instance, branch, change, and so on).
|
save, out, and in
|
- If your trigger script needs to know what files were (or are about to be) submitted in the changelist, use the command p4 opened -ac changelist.
- Pre-submit trigger scripts cannot access submitted file contents from the server, because at the time a pre-submit trigger runs, file contents have not yet been transferred to the server.
- Perforce commands in trigger scripts are always run by a specific Perforce user. If no user is specified, an extra Perforce license for a user named SYSTEM (or on UNIX, the user that owns the p4d process) is assumed. To prevent this from happening:
- Pass a %user% argument to the script that calls each Perforce command to ensure that each command is called by. For example, if Joe submits a changelist that activates trigger script trigger.pl, and trigger.pl calls the p4 changes command, the script can run the command as p4 -u %user% changes.
- Set P4USER for the account that runs the trigger script to the name of an existing user. (If your Perforce server is installed as a service under Windows, note that Windows services cannot have a P4USER value; on Windows, you must therefore pass a user value to each command as described above.)
- For the three specification trigger types (in, out, and save), the %formname% variable is unset on job creation. This limitation is due to the fact that a job's name is unknown to the server until after job creation. After job creation, subsequent user changes to a job correctly set %formname% for use by specification trigger scripts.
Examples
Suppose that the trigger table consists of the following entries:
|
trig1 submit //depot/dir/... "/usr/bin/s1.pl %changelist%"
trig2 submit //depot/dir/file "/usr/bin/s2.pl %user%"
trig1 submit -//depot/dir/z* "/usr/bin/s1.pl %user%"
trig1 submit //depot/dir/zed "/usr/bin/s3.pl %client%"
|
Both the first and fourth lines call the script /bin/s1.pl %changelist%, because the first occurrence of a particular trigger name determines which script is run when the trigger name is subsequently used.
No triggers are activated if someone submits file //depot/dir/zebra, because the third line excludes this file. If someone submits //depot/dir/zed, the trig1 script /usr/bin/s1.pl %changelist% is run: although the fourth line overrides the third, only the first script associated with the name trig1 is called.
For more detailed examples, see the System Administrator's Guide.
Please send comments and questions about this manual to
[email protected].
Copyright 1999-2004 Perforce Software. All rights reserved.
Last updated: 08/19/04