Detailed reference for triggers in Unity Version Control.
Read time 27 minutesLast updated 21 days ago
The following section provides a detailed reference of all the triggers as well as input and output parameters. Samples are provided for the most common actions.
Add
Heading
Value
Trigger names
before-add
after-add
Description
It executes user scripts when items are added to the source control.
Runs on
Server
Filters
You can use the following filters:
Repository name
Standard input
For example, if
--filter="rep:test,*.cs"
, then the trigger executes only for repository
test
and if at least one of the lines in the standard input is about adding a C# file.
Standard input
A list of files to be added.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
The trigger was completed successfully. The items will be added.
The comment given by the user on the add operation.
Checkin
Heading
Value
Trigger names
before-checkin
after-checkin
Description
It executes user scripts when a checkin operation is performed on any client.
Runs on
Server
Filters
You can use the following filters:
Repository name
Standard input
For example, if
--filter="rep:code,CH *search.c*"
, then the trigger executes only for repository
code
and if at least one of the lines in the standard input is about a change (
CH
)
in a
*search.c*
file.
Standard input
The standard input receives revision identifiers for all the items involved in the checkin operation, one per line. Each of them is a specially formatted string containing the server's path of the item (independent of any workspace) and the revision specification, so its contents are easily retrieved using the
cm cat
command.This is the format of the revision specifications, one per line:
status item_path item_type#br:branch;changeset:cset_id@@rep:rep_name@@repserver:server
The meaning of the members in italic is detailed in the following table:
Member
Description
status
The status of the item to be checked in: added (AD), changed (CH), moved (MV), deleted (DE)...
item_path
The revision's path in server format, which is independent of the client workspace and operating system.
item_type
The type of the item: DIR or FILE.
branch
The branch of the revision.
cset_id
Only available in the
after-checkin
trigger. The unique changeset identifier. Can be used to ease parsing when accessing revisions with
cm cat
or
cm shelveset
in the trigger script, as the string after the first semicolon uniquely identifiesthe revision inside the server.
rep_name
The repository name where the revision belongs.
server
The repository server and port where the repository belongs.
This example shows standard input supplied to a checkin trigger when making a checkin to the
Result code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
The trigger completed successfully. Items will be checkedin the repository.
Non zero
The trigger reports failure. If the trigger is
before-checkin
the checkin operation is stopped, and the items are not checked in, neither changeset is created. An error message is reported to the client. If the trigger is
after-checkin
, an error message is reported to the client. However, the checkin operation has already been performed.
This variable indicates whether the checkin is a shelve operation or not.
PLASTIC_CHANGESET
Only available in the
after-checkin
trigger. The changeset or changesets that were created as a result of the checkin operation. This variable contains the specifications for the changesets that were created, separated by semi-colons (
;
). This is a sample of a variable value with changesets created on two different repositories:
: the source changeset specification of the mergelink, composed of the changeset number, the repository, and the server.
base
(optional): if mergetype is
intervalcherrypick
or
intervalcherrypicksubtractive
then it's the base changeset specification of the selected interval. Otherwise, the field doesn't appear in the serialized string.
PLASTIC_MERGE_LINKS
Same as PLASTIC_PENDING_MERGE_LINKS environment variable but only available in the
after-checkin
trigger.
Comments
The
before-checkin
and
after-checkin
triggers are invoked only once for all the items involved in the checkin operation. The standard input of the trigger will receive a list of the items involved.This is one of the most complex and useful triggers. Some examples of usages: Checking code before it is checked in on the repository against some validation/formatting tool or sending emails/updating rss feeds when new code is in the repository.Revision contents can be accessed through the
cm cat
command, specifying the revision specification supplied in the standard input. They can be validated, modified, and then stored back into the server with the
cm shelveset
command. In case a
shelveset
command updates the contents of a revision in the repository, the client performing the checkin operation will automatically update those items, so the contents of the workspace are always correct.
Sample command line creation
cm trigger create checkin-before "checkstyle" "c:\tmp\triggers\checkin-checkstyle.bat"Trigger created on position 1.
Sample trigger script
The following script reads all the standard input and redirects it to the
c:\tmp\triggers\checkinout.txt
file. The trick here is the use of the
find.exe
command to read the standard input in Windows command line
cmd.exe
:
@@echo offfor /f "tokens=*" %%g in ('find /V ""') do (echo %%g >> c:\tmp\triggers\checkinout.txt)exit 0
Merge
Heading
Value
Trigger names
before-merge
Description
This trigger can be used to deny the merge of some branches if certain conditions are not met.
Runs on
Server
Filters
You can use the following filters:
Repository name
Standard input
For example, if
--filter="rep:dev*,*EVIL*"
, then the trigger executes only for repositories whose
name starts with
dev
and if at least one line in the standard input is an
evil
merge
conflict.
Standard input
The standard input for the
merge
and the
mergeTo
actions is one of the following:If the merge operation can't be performed, then the standard input is the reason why:
Code
Description
CONTRIBUTORS_NOT_CONNECTED
Source and destination are not connected. Returned by the subtractive merge.
INVALID_CSET_INTERVAL
The selected changesets interval
(base, source]
is not valid.
ANCESTOR_NOT_FOUND
No ancestor found between source and destination.
CONTRIBUTORS_ALREADY_CONNECTED
Source is already included on destination. Merge not needed.
SOURCE_ALREADY_SUBTRACTED
The source is already subtracted from the destination. Subtractive merge not needed.
NO_MERGES_DETECTED
There are no changes between source and destination.
If the merge operation is performed, the standard input is a list of conflicts in the following order:
Directory conflicts
File conflicts
Writable xlinks conflicts
Then add the operations to apply (source changed, deleted, added, and so on). Each conflict and operation must be one per line. Refer to the following examples for each type:
Conflicts
ADD_MOVE [SRC] A "/foo.c" cs:10 - [DST] M "/bar.c" -> "/foo.c" cs:5
CHANGE_DELETE [SRC] C "/foo.c" cs:12 (base cs:7) - [DST] D "/foo.c" cs:7
CYCLE [SRC] M "/server" -> "/bin/server" cs:5 - [DST] M "/bin" -> "/server/bin" cs:5
DELETE_CHANGE [SRC] D "/foo.c" cs:7 - [DST] C "/foo.c" cs:12 (base cs:7)
DELETE_MOVE [SRC] D "/foo.c" cs:10 - [DST] M "/foo.c" -> "/bar.c" cs:10
DELETE_MOVE [SRC] D "/foo.c" cs:10 - [DST] M "/foo.c" -> "/bar.c" cs:10
DIVERGENT_MOVE [SRC] M "/foo.c" -> "/bar.c" cs:5 - [DST] M "/foo.c" -> "/qux.c" cs:5
EVIL_TWIN [SRC] A "/foo.c" cs:10 - [DST] A "/foo.c" cs:5
LOADED_TWICE [SRC] A "/bar.c" cs:10 - [DST] A "/foo.c" cs:5
MOVE_ADD [SRC] M "/bar.c" -> "/foo.c" cs:10 - [DST] A "/foo.c" cs:5
MOVE_DELETE [SRC] M "/foo.c" -> "/bar.c" cs:10 - [DST] R "/foo.c" cs:10
MOVE_EVIL_TWIN [SRC] M "/foo.c" -> "/qux.c" cs:10 - [DST] M "/bar.c" -> "/qux.c" cs:5
XLINK_CONFLICT [SRC] C "/thirdparty" Xlink ->/eb50a746-ab55-4c92-91e4-f98a62cd599f@libs@relativeServer (base Xlink ->/b69de40f-7693-46c6-a9e5-9359a162a39a@libs@relativeServer) - [DST] C "/thirdparty" Xlink ->/ba682b83-4aaf-4169-b1ad-3d8de14b371b@libs@relativeServer (base Xlink ->/b69de40f-7693-46c6-a9e5-9359a162a39a@libs@relativeServer) FILE_CONFLICT [SRC] C "/foo.c" cs:12 (base cs:7) - [DST] C "/foo.c" cs:8 (base cs:7)
Writable Xlinks conflicts that will be expanded with a new merge
XLINK_MERGE [SRC] C "/engine" wXlink ->/235163d5-99c2-4490-988d-204ddd76d963@engine@relativeServer (base wXlink ->/be492aa6-d42d-45be-a7b3-b7d0346fb74f@engine@relativeServer) - [DST] C "/engine" wXlink ->/17cb0014-3351-45f2-9ecb-bc025a43d059@engine@relativeServer (base wXlink ->/be492aa6-d42d-45be-a7b3-b7d0346fb74f@engine@relativeServer)
XLINK_MERGE [SRC] C "/engine" wXlink ->/235163d5-99c2-4490-988d-204ddd76d963@engine@relativeServer (base wXlink ->/be492aa6-d42d-45be-a7b3-b7d0346fb74f@engine@relativeServer)
Operations to apply
C "/foo.c" cs:12 (base cs:7)
C "/thirdparty" Xlink ->/eb50a746-ab55-4c92-91e4-f98a62cd599f@libs@relativeServer (base Xlink ->/b69de40f-7693-46c6-a9e5-9359a162a39a@libs@relativeServer)
A "/foo.c" cs:7
M "/foo.c" -> "/bar.c" cs:7
D "/foo.c" cs:7
FS "/foo.c" 777 (base 444)
This is an example for a simple merge:
CHANGE_DELETE [SRC] C "/src/foo.c" cs:12 (base cs:7) - [DST] D "/src/foo.c" cs:7FILE_CONFLICT [SRC] C "/src /bar.c" cs:12 (base cs:7) - [DST] C "/src /bar.c" cs:8 (base cs:7)M "/doc/readme.txt" -> "/readme.txt" cs:7D "/doc" cs:7
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
The repository name where the label is being created.
PLASTIC_CHANGESET_NUMBER
The number of the changeset being labeled.
PLASTIC_CHANGESET_OWNER
The name of the owner of the changeset being labeled.
Sample command-line creation
cm trigger create before-mklabel "Validate label" "c:\plastic\triggers\Validate-label.bat" --filter="LB*"Trigger created on position 1.cm trigger list before-mklabel1 Validate label c:\plastic\triggers\Validate-label.bat dave
Sample trigger script
The following script saves a record of created branches on the c:\plastic\triggers\labels.log.txt file.
It executes user scripts when a workspace is created.
Runs on
Client.
Filters
You can use the following filters:
Repository name
Workspace name
For example, if
--filter="rep:cod*,code"
, the trigger executes only for workspace
code
in all repositories whose name starts with
cod
.
Standard input
No standard input is supplied to these triggers.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
The trigger completed successfully. The workspace will be created.
Non zero
The trigger reports failure. If the trigger is
before-mkworkspace
, an error is reported, and the workspace is not created. If the trigger is
after-mkworkspace
, an error is reported. However, the workspace has already been created.
Environment variables
In addition to the variables defined in section Common environment variables, the following ones are also available:
Environment variable
Description
PLASTIC_WORKSPACE_NAME
The name given to the new workspace.
PLASTIC_WORKSPACE_PATH
The path of the workspace on the client machine.
Set selector
Heading
Value
Trigger names
before-setselector
after-setselector
Description
Executes user scripts when a workspace selector is changed.
Runs on
Client.
Filters
You can use the following filters:
Repository name
Standard input
For example, if
--filter="rep:test,/main/Release*"
, the trigger executes only for repository
test
and if at least one line in the standard input matches
/main/Release*
.
Standard input
The standard input in these triggers receives the selector contents that the client is setting.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
The trigger completed successfully. The selector will be modified.
Non zero
The trigger reports failure. If the trigger is
before-setselector
, an error is reported, and the selector is not modified. If the trigger is
after-setselector
, an error is reported. However, the operation has already been done.
Environment variables
In addition to the variables defined in section Common environment variables, the following ones are also available:
Environment variable
Description
PLASTIC_WORKSPACE_NAME
The name of the workspace which selector is being set.
PLASTIC_WORKSPACE_PATH
The client path of the workspace which selector is being set.
Comments
Selectors are modified either with the
setselector
or
switch
command or with the Switch workspace to branch, Switch workspace to label or Switch workspace to changeset commands, all of them in the command-line interface or the GUI client.
Update
Heading
Value
Trigger names
before-update
after-update
Description
It executes user scripts in the following scenarios:
When a workspace is updated.
When a
fast-update
operation is executed.
When a Gluon workspace is updated (both from the Gluon GUI or by running the cm partial update command).
Runs on
Client.
Filters
You can use the following filters:
Repository name
Path to be updated
Standard input
For example, if
--filter="rep:code,D:*/lib*"
, then the trigger executes only for repository
code
and if at least one of the lines in the standard input is about deleting (
D
)
items in a
lib
path.
Standard input
If the trigger is
before-update
, then no standard input is supplied to this trigger.If the trigger is
after-update
, then the standard input is
<{0}:{1}>
, where:
{0}
is the change's type:
C: Created (new item).
U: Updated.
M: Modified on disk (implies not updated nor deleted).
D: Deleted.
{1}
is the change's path.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
The trigger completed successfully. Update operation will proceed.
Non zero
The trigger reports failure. If the trigger is
before-update
, an error is reported, and the workspace is not updated. If the trigger is
after-update
, an error is reported. However, the workspace has already been updated.
Environment variables
In addition to the variables defined in the Common environment variables section, the following is also available:
Environment variable
Description
PLASTIC_UPDATE_PATH
The client path of the workspace that is being updated.
PLASTIC_INITIAL_CHANGESET
The ID of your workspace's changeset is (or was) pointing at when the update begins.
PLASTIC_FINAL_CHANGESET
The ID of the changeset your workspace is (or will be) pointing at when the update finishes.
Comments
This trigger runs on the client, so the script locations are relative to the client machine filesystems. This is an important difference to note when creating these kinds of triggers.
Create code review
Heading
Value
Trigger names
before-mkreview
after-mkreview
Description
It executes user scripts when a code review is created.
Runs on
Server
Filters
You can use the following filters:
Repository name
Code review title
For example, if
--filter="rep:development,Review*"
, the trigger executes only for code reviews
whose title starts with
Review
in the repository
development
.
Standard input
No standard input is supplied to these triggers.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
The trigger completed successfully. The code review will be created.
Non zero
The trigger reports failure. If the trigger is
before-mkreview
, an error is reported, and the code review is not created. If the trigger is
after-mkreview
, an error is reported. However, the code review has already been created.
The repository name where the code review is created.
PLASTIC_REVIEW_TITLE
The title given to the code review.
PLASTIC_REVIEW_STATUS
Under review
,
Reviewed
, or
Rework Required
.
PLASTIC_REVIEW_ASSIGNEE
The user assigned to the code review, if any. Not set if no user is assigned to the code review
PLASTIC_REVIEW_TARGET
The specification of the object for which the code review has been created. Either a changeset or a branch.
PLASTIC_REVIEW_TARGET_TYPE
branch
/
changeset
.
PLASTIC_REVIEW_ID
Only available in the
after-mkreview
trigger. The variable contains the identifier of the review that has been created.
Edit code review
Heading
Value
Trigger names
before-editreview
after-editreview
Description
It executes user scripts when a code review is edited. For example, the triggers will be launched when a user changes a review name, the assignee, or the status, or when a review comment is created, edited, or deleted.
Runs on
Server
Filters
You can use the following filters:
Repository name
Code review title
For example, if
--filter="rep:development,Review*"
, the trigger executes only for code reviews
whose title starts with
Review
in the repository
development
.
Standard input
No standard input is supplied to these triggers.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
The trigger completed successfully. The code review edition is saved to the repository.
Non zero
The trigger reports failure. If the trigger is
before-editreview
, an error is reported, and the code review edition is not saved in the repository. If the trigger is
after-editreview
, an error is reported. However, the code review edition is saved to the repository.
The repository name where the code review is edited.
PLASTIC_REVIEW_TITLE
The title given to the edited code review.
PLASTIC_REVIEW_STATUS
Under review
,
Reviewed
, or
Rework Required
.
PLASTIC_REVIEW_ASSIGNEE
The user assigned to the code review, if any. Not set if no user is assigned to the code review
PLASTIC_REVIEW_TARGET
The specification of the object for which the code review has been edited. Either a changeset or a branch.
PLASTIC_REVIEW_TARGET_TYPE
branch
or
changeset
.
PLASTIC_REVIEW_ID
The variable contains the identifier of the edited review.
PLASTIC_REVIEW_COMMENT
The variable contains the comment that fired the trigger. This variable will be empty if the action that fired the trigger is changing the code review status or the assignee.
PLASTIC_REVIEW_COMMENT_ACTION
The variable reflects the action in the comment:
Created
,
Edited
, or
Deleted
. This variable will be empty if the action that fired the trigger is changing the code review status or the assignee.
Client checkout
Heading
Value
Trigger names
before-clientcheckout
after-clientcheckout
Description
It executes user scripts on the client when a checkout operation is executed.
Runs on
Client.
Filters
You can use the following filter:
Repository name
Standard input
For example, if
--filter="rep:code,*.json"
, then the trigger executes only for repository
code
and if at least one of the lines in the standard input is about running a checkout on a
json
file.
Standard input
The standard input in these triggers receives the list of items specified by the user on the checkout operation.
Output result
The resulting code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
The trigger completed successfully. Checkout operation will proceed.
Non zero
The trigger reports failure. If the trigger is
before-clientcheckout
, an error is reported, and the operation is canceled. If the trigger is
after-clientcheckout
, an error is reported. However, the items have been already checked out.
This trigger runs on the client, so the script locations are relative to the client machine filesystems. This is an important difference to note when creating these kinds of triggers.
Client checkin
Heading
Value
Trigger names
before-clientcheckin
after-clientcheckin
Description
It executes user scripts on the client when a checkin operation is executed.
Runs on
Client.
Filters
You can use the following filters:
Repository name
Standard input
For example, if
--filter="rep:code,*src*"
, then the trigger executes only for repository
code
and if at least one of the lines in the standard input affects an
*src*
item.
Standard input
The standard input in these triggers receives the list of items specified by the user on the checkin operation.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
The trigger completed successfully. Checkin operation will proceed.
Non zero
The trigger reports failure. If the trigger is
before-clientcheckin
, an error is reported, and the checkin operation is aborted. If the trigger is
after-clientcheckin
, an error is reported. The items are already checked in.
Environment variables
In addition to the variables defined in section Common environment variables, the following ones also available:
Environment variable
Description
PLASTIC_COMMENT
The comment specified by the user on the checkin operation.
PLASTIC_CHANGESET
Only available in the
after-clientcheckin
trigger. The changeset or changesets that were created as a result of the checkin operation.
PLASTIC_PENDING_MERGE_LINKS
Only available in the
before-clientcheckin
trigger. The variable contains the following information:
The merge links included in the checkin operation.
The merge links affecting the repositories under a xlink.
: the source changeset specification of the mergelink, composed of the changeset number, the repository, and the server.
base
(optional): if mergetype is
intervalcherrypick
or
intervalcherrypicksubtractive
then it's the base changeset specification of the selected interval. Otherwise, the field doesn't appear in the serialized string.
PLASTIC_MERGE_LINKS
Same as
PLASTIC_PENDING_MERGE_LINKS
environment variable but only available in the
after-clientcheckin
trigger.
Comments
This trigger runs on the client, so the script locations are relative to the client machine filesystems. This is an important difference to note when creating these kinds of triggers.
The
before-clientcheckin
trigger runs once per affected repository under an Xlink and then again for the repository where the checkin occurs. If you don't want this to happen, you can add a filter.
Security
Heading
Value
Trigger names
after-security
Description
It executes user scripts when a user performs an operation that has been denied through security permissions.
Runs on
Server
Filters
You can use the following filter:
Repository name
For example, if
--filter="rep:docu"
, the trigger executes only for repository
docu
.
Standard input
No standard input is supplied to this trigger.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
The trigger completed successfully. Security operation will proceed.
Non zero
The trigger reports failure. If the trigger is
after-security
, an error is reported.
Environment variables
In addition to the variables defined in section Common environment variables, the following ones also available:
Environment variable
Description
PLASTIC_MESSAGE
The information about the denied permission.
PLASTIC_PERMISSIONS
The denied permissions.
PLASTIC_REPOSITORY_ID
The ID of the repository where the operation is executed.
PLASTIC_REPOSITORY_NAME
The name of the repository where the operation is executed.
PLASTIC_OBJECT
The object with the denied permission.
Replication read
Heading
Value
Trigger names
before-replicationread
after-replicationread
Description
It executes user scripts when a user performs a replication operation that involves reading data. This occurs:
In the source side on a push operation.
In the source side on a pull operation.
Runs on
Server
Filters
You can use the following filter:
Repository name
For example, if
--filter="rep:code"
, then the trigger executes only for repository
code
.
Standard input
No standard input is supplied to these triggers.
Output result
Result code from the trigger script or executable determines the success or failure of the operation:
Output result
Description
0
Success.
Non zero
Failure. If
before-replicationread
, the operation is aborted. If
after-replicationread
, the item is already replicated.
Environment variables
Environment variable
Description
PLASTIC_BRANCH
Complete branch specification being replicated: This is the format of the branch specification:
branch@rep:rep_name@server
. If the trigger is
before-replicationread
,
server
is destination. If the trigger is
after-replicationread
,
server
is the source.
Replication write
Heading
Value
Trigger names
before-replicationwrite
after-replicationwrite
Description
Executes user scripts when a replication operation writes data (destination side of push/pull).
Runs on
Server
Filters
You can use the following filter:
Repository name
For example, if
--filter="rep:code"
, the trigger executes only for repository
code
.
Standard input
No standard input is supplied to these triggers.
Output result
Result code from the trigger script or executable determines the success or failure of the operation: