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 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 look the same, and prevent the script from being executed on that 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.

  • 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:

⬆ ⬇ ⇧

about:

⬆ ⬇ ⇧

unmht:

⬆ ⬇ ⇧

.tld

⬆ ⬇ ⇧

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

Notes