Script_injection_rules

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 UserScript 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 a key value of 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 may look the same but prevent the script from being executed on this pattern regardless of @include or @match allowances.

⬆ ⬇ ⇧

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/. However please don't shout.

• @exclude values may look the same but prevent the script from being executed on this pattern regardless of @include or @match allowances.

• JavaScript RegExp currently allows forward slashes and trailing matches to be non-escaped and omitted respectively. See special characters. Therefore /^https?://www\.example.org// should be the same as /^https?:\/\/www\.example.org\/.*/ in this context. However in other contexts the shorthand syntax may be considered non-portable and may not be 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:

• Only if about:config?filter=greasemonkey.fileIsGreaseable is set to true.

⬆ ⬇ ⇧

about:

• Only about:blank is currently allowed.

⬆ ⬇ ⇧

unmht:

• Only if about:config?filter=greasemonkey.unmhtIsGreaseable is set to true.

⬆ ⬇ ⇧

.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 one 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

⬆