Greasemonkey / Wiki / Script_injection_rules
Menu ▾ ▴

Script_injection_rules

mmartz
There is a newer version of this page. You can find it here.

Getting Started ⬌ Installing Scripts ⬌ Managing Scripts ⬌ Monkey Menu ⬌ Creating Scripts ⬌ Environment ⬌ Other Useful Tools ⬌ API

In general user scripts should specify at least one @include or at least one @exclude in the metadata block.

The script will execute if a user script matches any @include, as long as it does not match an @exclude or a global exclude.

If no @include is provided, @include * is assumed. That is, every URL will be matched within the allowed Pattern recognitions.

⬆ ⬇

Patterns

Patterns apply to @include, @match, and @exclude values including global excludes unless otherwise specified.

Pattern recognition

Pattern matching

Regular Expressions

Globs

// ==UserScript==
//
// @include   http://www.example.org/*
// @include   https://www.example.org/*
//
// @match     http://www.example.net/*
// @match     https://www.example.net/*
//
// @exclude   http://www.example.com/*
// @exclude   https://www.example.com/*
//
// ==/UserScript==
  • These names to values are URLs, which can have a "wildcard" asterisk (*), which matches any string including the empty string. For example // @include https://www.example.org/foo/* will match https://www.example.org/foo/bar and https://www.example.org/foo/, but not https://www.example.org/baz/. A value can have several wildcards or none, in which case the value must match the entire URL exactly. Exclude values look the same, and prevent the script from being executed.

⬆ ⬇ ⇧

Regular Expressions

// ==UserScript==
//
// @include   /^https?:\/\/www\.example.(?:org|net)\/.*/
//
// @exclude   /^https?:\/\/www\.example.com\/.*/
//
// ==/UserScript==
  • Currently these patterns are supported on @include, and @exclude and global excludes only.
  • This pattern is always treated as case insensitive therefore a Url in the address bar of HTTPS://WWW.EXAMPLE.ORG/ is the same as https://www.example.org/.

  • JavaScript RegExp currently allows forward slashes and trailing match the preceding item 0 or more times special character to be non-escaped and omitted respectively. Therefore /^https?://www\.example.org/.*/ should be the same as /^https?:\/\/www\.example.org\/.*/ in this context. However in other contexts this shorthand syntax is considered non-portable and is not recommended due to potential cross-browser differences. Better to be safe than sorry later on.

⬆ ⬇ ⇧

Pattern recognition

⬆ ⬇ | file: | about: | unmht:| .tld

http:

https:

ftp:

  • Generally these are the most common schemes, or protocols, that user scripts inject into.

⬆ ⬇ ⇧

file:

⬆ ⬇ ⇧

about:

⬆ ⬇ ⇧

unmht:

⬆ ⬇ ⇧

.tld

  • A value such as https://www.example.tld/* will match any top level domain, such as https://www.example.com, https://www.example.org, https://www.example.co.uk, and so on. One must be careful with this, to not accidentally leak data to a site that they did not mean to match. This list of TLDs includes a myriad of dual-segment TLDs (such as ca.us, aeroport.fr and kyoto.jp), beside the plain country or category codes (com, jp, se). For a full list see this list.
    NOTE: Some of these may not be incorporated into Greasemonkey and is issued at greasemonkey/greasemonkey#1351
  • .tld currently only works in glob pattern matching and not in regular expression pattern matching.

⬆ ⬇ ⇧

Getting Started ⬌ Installing Scripts ⬌ Managing Scripts ⬌ Monkey Menu ⬌ Creating Scripts ⬌ Environment ⬌ Other Useful Tools ⬌ API

Notes