Include and exclude rules

From GreaseSpot Wiki
Revision as of 11:47, 13 March 2018 by Joeytwiddle (talk | contribs) (Recommend @match over @include)
Jump to navigationJump to search

User scripts specify include and exclude rules in the metadata block.

The script will execute if it matches any include rule, as long as it does not match an exclude rule.

Please note: The @match rule is safer than the older @include rule, and now widely supported, so you are recommended to use that instead. Read about the @match rule here.

Globs

Include and exclude rules support the * or globbing operator. The * serves as a wildcard that matches one or more of any character. A rule can have several wildcards or none, in which case the rule must match the entire URL exactly. Exclude rules look the same, and prevent the script from being executed.

For example: http://www.example.com/foo/* will match:

  • http://www.example.com/foo/bar and,
  • http://www.example.com/foo/

but not:

  • http://www.example.com/baz/.

Further examples:

// ==UserScript==
// @include     http://www.example.com/foo/*
// @include     http://www.example.org/*.bar
// @exclude     http://www.example.com/foo/baz
// ==/UserScript==

If no include rule is provided, @include * is assumed. That is: every URL will be matched, within the allowed Greaseable schemes.

Regular Expressions

Support for full regular expressions in include and exclude rules is also available. If the rule both starts and ends with a forward-slash (/) character, the contents inside those slashes are interpreted as a regular expression. For example:

// ==UserScript==
// @include     /^https?://www\.example\.com/.*$/
// @include     /^http://www\.example\.(org|net)//
// ==/UserScript==

Note:

  • The rule is parsed as a standard javascript new RegExp(), so you do not need to escape forward slashes inside the rule. Special regex characters (like .) should still be escaped, as in the above examples; otherwise they have their normal regex meaning (like . matching any non-newline character).
  • The rule is always treated as case insensitive.
  • Anchors (^, $) are not supplied for you. If desired, they should be used as in the above example.

Greaseable schemes

Greasemonkey will run scripts only on documents loaded from particular schemes. By default, those are:

  • http
  • https
  • about:blank

User scripts will not run on documents from any other scheme (ftp, file, etc.) or any other part of about.