How to apply filters to triggers

How to apply filters to triggers

Thursday, October 24, 2019 María Barrios Carrasco best practices 0 Comments

Some days ago, we published a new update to the Triggers guide about how filters work with triggers.

As you may already know, the trigger system in Plastic SCM allows the execution of user commands at certain points in the client or server execution workflow, in the form of shell scripts or any other operating system executable.

Among others, the trigger system in Plastic SCM will allow the developer or administrator to perform the following tasks:

• Enforce branch creation policies like naming conventions or making sure that branch names always refer to a certain associated task.
• Introduce before-checkin rules to enforce coding standards or create formatting rules.
• Enforce that comments are introduced on checkin.

Triggers are created from the command line client:

cm trigger create {type} {name} {script}
  [--position=value]
  [--filter=filter-value]
  [--server=server:port]

and you must use the --filter option if you want to restrict when the trigger executes.

This blogpost is a summary of the explanation and examples that we included in the Triggers guide.

How do filters work?

The option --filter creates a trigger that will be executed only when the fields specified in the filter match the repository, object, or path involved in the operation that triggered the execution.

1. Filters admit regular expressions.
2. Filters are a comma separated list.
3. If you need to use a comma character inside a filter, don't forget to scape it: \,.
4. The filters restrict when the trigger executes.
5. You can filter by repository (rep:) in all types of triggers. For example: --filter="rep:myrepo".
6. Then, the system checks every particular filter to each type of trigger.
7. If the trigger receives data from the standard input, then the filter applies to each line of this input before the trigger executes.
   Note that at least one filter must match with a line in the standard input. It is not necessary that all lines in the standard input match with the specified filters.

Which filters can be used with every trigger?

You can filter by repository (although not mandatory) in all types of triggers.

When filtering by repository, you have to include the prefix rep:. This is the only filtering case where you have to include a prefix.

Then, every type of trigger accepts some particular objects to filter by. Check the detailed trigger reference chapter in the Triggers guide to learn more about which filters can be used in every trigger.

Some examples

Thanks to Sergio for these examples 😉

Trigger:

before-mkbranch

Name:

"Check SemanticMegre branch naming policy"

Script:

/home/codice/triggers/after-mkbranch.sh

Filters:

• Only apply the filter to repository codice
• Only apply the to branches wich name starts with sm

> cm trigger create before-mkbranch \
      "Check SemanticMerge branch naming policy" \
      /home/codice/triggers/after-mkbranch.sh \
      --filter="rep:codice,sm*"

Trigger:

after-checkin

Name:

"Check style"

Script:

c:\tmp\triggers\checkin-checkstyle.bat

Standard input:

CH "/" DIR#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087 CH "/search" DIR#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087 CH "/search/search.h" FILE#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087

Filters:

• Only apply the to changed items in files which name contains search.c
• Only apply the to changed items in files which name contains search.h

> cm trigger create after-checkin \
      "Check style" \
      c:\tmp\triggers\checkin-checkstyle.bat \
      --filter="CH *search.c*,CH *search.h*"

How do these filters work?

• We have two filters:
  F1) CH *search.c*
  F2) CH *search.h*
• And three standard input lines:
  L1) CH "/" DIR#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087
  L2) CH "/search" DIR#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087
  L3) CH "/search/search.h" FILE#br:/main/scm001;changeset:61@rep:doom3src@repserver:HERMES:8087
• Now it's time to match the filters with the lines to check if the trigger executes or not:
  • F1 → L1: NO
  • F1 → L2: NO
  • F1 → L3: NO
  • F2 → L1: NO
  • F2 → L2: NO
  • F2 → L3: YES

Because there is one filter that matches with one of the standard input lines, then the trigger executes. If no match would exist, then the trigger doesn't execute.

Wrapping up

As you've seen before, filters provide you with the ability to decide when the trigger executes or not.

Remember that you can find the complete explanation about how to apply filters in every type of trigger in the Triggers guide.

María Barrios Carrasco

I'm in charge of the documentation area and the one to let you know the news about our products: Plastic SCM, SemanticMerge and gmaster.
I started my degree in Computer Engineering at the University of Burgos and finished my studies at the University of Valladolid.
I love doing handmade crafts, going for a walk and for tapas 😋.
You can reach me at @maria13mbc.