p4 triggers
Synopsis
Edit a list of scripts to be run conditionally whenever changelists are submitted.
Syntax
p4 [g-opts] triggers
p4 [g-opts] triggers -i
p4 [g-opts] triggers -o
Description
A pre-submit trigger is a user-written script that Perforce has been told to run whenever particular files are submitted in a changelist. If the script returns a value of 0, the submit continues; if it returns any other value, the submit fails. Upon failure, the script's standard output (not error output) is used as the text of the failed command's error message.
Triggers are run in the order listed in the table; if one trigger script fails, subsequent trigger scripts are not run. Even when a trigger script succeeds, the submit may fail because of subsequent triggers, or for other reasons. Thus, pre-submit triggers should be used only for validation, and should not perform operations that are dependent on the successful completion of the submit. If this is necessary, create a daemon instead.
To use the same trigger script with multiple file patterns, list the same trigger multiple times in the trigger table. Exclusionary mappings can be provided to exclude files from activating the trigger script; in this case, the order of the trigger entries matters, just as it does when exclusionary mappings are used in views (see the Examples section, below).
If a particular trigger name is listed multiple times, only the script corresponding to the first use of the trigger name is activated.
Form Fields
The p4 triggers form contains a single field, called Triggers:. Each row in the table holds three values:
Column
|
Description
|
|---|
|
Trigger Name
|
The name of the trigger; an arbitrary string.
|
|
File Pattern
|
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 will be run.
|
|
Trigger Script
|
A script accessible from the Perforce server. Arguments can be passed to this script; a list of valid arguments is provided in the Usage Notes below.
The script and its arguments should be quoted.
|
Options
|
-i
|
Reads the trigger table from standard input without invoking the user's editor.
|
|
-o
|
Writes the trigger table to standard output without invoking the user's 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
|
- Arguments may be passed to the trigger script, and are specified in the trigger table as follows:
Argument
|
Description
|
|---|
|
%changelist%
|
The number of the changelist being submitted. (The abbreviated form %change% is also acceptable)
|
|
%client%
|
Name of the client workspace that submitted the changelist
|
|
%clienthost%
|
Hostname of the client
|
|
%clientip%
|
The IP address of the client
|
|
%serverhost%
|
Hostname of the Perforce server
|
|
%serverip%
|
The IP address of the server
|
|
%serverport%
|
The IP address and port of the Perforce server, in the format ip_address:port
|
|
%serverroot%
|
The value of the server's P4ROOT; the top-level directory of the server's files and metadata
|
|
%user%
|
The Perforce username of the user who submitted the changelist
|
- If your trigger script needs to know which files were submitted in the changelist, use the command p4 opened -ac changelist#.
- The trigger script can't access the submitted file contents from the server, since the files have not yet been stored there. But if the server has access to the client machine, the file contents can be obtained from the client via OS commands.
- Perforce commands in trigger scripts are always run by a specific Perforce user. If this is not properly planned for, an extra Perforce license for a user named SYSTEM might be consumed. Some of the other options are:
- Use the %user% argument to the script within each Perforce command so that the script is run by the submitting user. For example, if Joe has submitted a changelist that activates trigger script trigger.pl, and this script runs the p4 changes command, the script can run the command 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 can't have P4USER values, and you must therefore use the script's %user% value).
- In order to use triggers, the server (p4d) must be able to "fork", or spawn off processes to run the triggers. This is the default configuration of Perforce. If you start p4d with the -f (run in foreground without forking) option, however, you will not be able to use triggers until you restart the server without the -f option.
Examples
Suppose that the trigger table consists of the following entries:
|
trig1 //depot/dir/... "/usr/bin/s1.pl %changelist%"
trig2 //depot/dir/file "/usr/bin/s2.pl %user%"
trig1 -//depot/dir/z* "/usr/bin/s1.pl %user%"
trig1 //depot/dir/zed "/usr/bin/s3.pl %client%"
|
Both the first and fourth lines call the script /bin/s1.pl %changelist%, since the first occurrence of a particular trigger name determines which script is run when that trigger name is subsequently used.
No triggers are activated if the user submits file //depot/dir/zebra, since the third line excludes this file, but if //depot/dir/zed is submitted, the trig1 script /usr/bin/s1.pl %changelist% will be run, since the fourth line overrides the third, and because the first script listed with the name trig1 is used.
Please send comments and questions about this manual to
[email protected].
Copyright 1999-2003 Perforce Software. All rights reserved.
Last updated: 12/12/03