javascriptgreasemonkeyuserscriptstampermonkey

What is the difference between @include and @match in userscripts?


The GreaseSpot page on metadata blocks says that the two are very similar but @match "sets more strict rules on what the * character means." GreaseSpot then proceeds to teach using @include, but Chrome examples like this generally seem to use @match and indicate that @include is only supported for compatibility purposes; @match is preferred.

Apparently, @include google.* can run on google.evil.com while @match google.* cannot.
That one example is not sufficient to really see how the wildcards behave differently between these two, and better explanations are sought in answers here.

New GreaseMonkey scripts (Firefox) use @include by default while new TamperMonkey scripts (for e.g. Chrome) use @match by default.

What exactly are the differences between these two?

For example, how does each one handle wildcards?
Are there differences in cross-browser compatibility?
What reasons would someone have for choosing to use one over the other?


Solution

  • You cannot use regular expressions with @match, while you can with @include.

    However, @include will give your users scarier security warnings about the script applying to all sites.

    This is even though an @include expression permits you to be more restrictive about the sites a script applies to (e.g. specifying that part of a URL be numeric using the regex fragment [0-9]+, or using ^https?:// to apply to a script just those two schemes, instead of the more general non-regex globbing operator * used for each of those cases in @match, which causes the script to apply more broadly).