minimatch

一个最小化的匹配工具。

这是npm内部使用的匹配库。

它通过将glob表达式转换为JavaScript RegExp对象来工作。

用法

// 混合模块，可以通过require()或import加载
import { minimatch } from 'minimatch'
// 或者：
const { minimatch } = require('minimatch')

minimatch('bar.foo', '*.foo') // true!
minimatch('bar.foo', '*.bar') // false!
minimatch('bar.foo', '*.+(bar|foo)', { debug: true }) // true，并且会输出调试信息！

特性

支持以下glob特性：

• 大括号展开
• 扩展的glob匹配
• "Globstar" ** 匹配
• Posix字符类， 如 [[:alpha:]]，支持全范围的Unicode字符。例如，[[:alpha:]] 将匹配 'é'， 而 [a-zA-Z] 则不会。不支持排序符号和集合匹配，所以 [[=e=]] 将不会匹配 'é'， [[.ch.]] 在将 ch 视为单个字符的语言环境中也不会匹配 'ch'。

参见：

• man sh
• man bash 模式匹配
• man 3 fnmatch
• man 5 gitignore

Windows

请在glob表达式中只使用正斜杠。

尽管Windows使用 / 或 \ 作为路径分隔符，但这个glob实现只使用 / 字符。 在glob表达式中，你必须只使用正斜杠。模式中的反斜杠将始终被解释为转义字符，而不是路径分隔符。

注意，在Windows上的路径中，\ 或 / 都会被解释为路径分隔符，并会匹配glob表达式中的 /。

所以在模式中始终使用 /。

UNC路径

在Windows上，像 //?/c:/... 或 //ComputerName/Share/... 这样的UNC路径会被特殊处理。

• 以双斜杠开头后跟一些非斜杠字符的模式将保留其双斜杠。因此，像 //* 这样的模式将匹配 //x，但不匹配 /x。
• 以 //?/<驱动器字母>: 开头的模式不会将 ? 视为通配符。相反，它将被视为普通字符串。
• 以 //?/<驱动器字母>:/... 开头的模式将匹配以 <驱动器字母>:/... 开头的文件路径，反之亦然， 就像 //?/ 不存在一样。这种行为仅在驱动器字母不区分大小写匹配时存在。 路径/模式的剩余部分会区分大小写进行比较，除非设置了 nocase:true。

注意，在文件路径参数中使用 \ 字符作为路径分隔符来指定UNC路径总是允许的， 但在模式参数中只有在选项中设置了 windowsPathsNoEscape: true 时才允许。

Minimatch类

通过实例化 minimatch.Minimatch 类来创建minimatch对象。

var Minimatch = require('minimatch').Minimatch
var mm = new Minimatch(pattern, options)

属性

• pattern minimatch对象表示的原始模式。

• options 传递给构造函数的选项。

• set 一个二维数组，包含正则表达式或字符串表达式。 数组中的每一行对应一个大括号展开的模式。每行中的每个项对应一个单独的路径部分。 例如，模式 {a,b/c}/d 会展开为一组如下的模式：

    [ [ a, d ]
    , [ b, c, d ] ]
  

  如果模式的一部分没有任何"魔法"（即，它是像 "foo" 这样的东西，而不是 fo*o?）， 那么它将保留为字符串，而不是转换为正则表达式。

• regexp 由 makeRe 方法创建。一个表示整个模式的单一正则表达式。 这在你希望以类似于启用了 FNM_PATH 的 fnmatch(3) 方式使用模式的情况下很有用。

• negate 如果模式是否定的，则为true。

• comment 如果模式是注释，则为true。

• empty 如果模式是 ""，则为true。

方法

• makeRe() 如果需要，生成 regexp 成员并返回它。如果模式无效，将返回 false。

• match(fname) 如果文件名匹配模式，则返回true，否则返回false。

• matchOne(fileArray, patternArray, partial) 接受一个以 / 分割的文件名， 并将其与 regExpSet 中的单行匹配。这个方法主要供内部使用， 但也暴露出来以便可以被需要避免过多文件系统调用的glob遍历器使用。

• hasMagic() 如果解析后的模式包含任何魔法字符，则返回true。 如果所有比较器部分都是字符串字面量，则返回false。如果在构造函数上设置了 magicalBraces 选项， 那么它会将否则不具有魔法的大括号展开视为魔法。如果未设置，那么像 a{b,c}d 这样的模式将返回 false， 因为 abd 和 acd 都不包含任何特殊的glob字符。

  这并不意味着模式字符串可以作为字面文件名使用，因为它可能包含被转义的魔法glob字符。 例如，模式 \\* 或 [*] 不会被认为具有魔法，因为匹配部分解析为字面字符串 '*'， 会匹配名为 '*' 的路径，而不是 '\\*' 或 '[*]'。minimatch.unescape() 方法 可用于移除转义字符。

所有其他方法都是内部方法，将根据需要调用。

minimatch(path, pattern, options)

主要导出。使用选项测试路径是否匹配模式。

var isJS = minimatch(file, '*.js', { matchBase: true })

minimatch.filter(pattern, options)

返回一个函数，该函数测试其提供的参数，适用于 Array.filter。例如：

var javascripts = fileList.filter(minimatch.filter('*.js', { matchBase: true }))

minimatch.escape(pattern, options = {})

转义glob模式中的所有魔法字符，使其只匹配字面字符串 如果使用了windowsPathsNoEscape选项，则字符会通过用[]包裹来进行转义，因为包裹在字符类中的魔法字符只能被该确切字符满足。

斜杠（以及在windowsPathsNoEscape模式下的反斜杠）无法被转义或取消转义。

minimatch.unescape(pattern, options = {})

取消对可能包含一些转义字符的glob字符串进行转义。

如果使用了windowsPathsNoEscape选项，则会移除方括号转义，但不会移除反斜杠转义。例如，它会将字符串'[*]'转换为*，但不会将'\\*'转换为'*'，因为在windowsPathsNoEscape模式下，\是路径分隔符。

当未设置windowsPathsNoEscape时，大括号转义和反斜杠转义都会被移除。

斜杠（以及在windowsPathsNoEscape模式下的反斜杠）无法被转义或取消转义。

minimatch.match(list, pattern, options)

以fnmatch或glob的风格匹配文件列表。如果没有匹配项，且设置了options.nonull，则返回包含模式本身的列表。

var javascripts = minimatch.match(fileList, '*.js', { matchBase: true })

minimatch.makeRe(pattern, options)

根据模式创建一个正则表达式对象。

选项

所有选项默认为false。

debug

向stderr输出大量信息。

nobrace

不展开{a,b}和{1..3}这样的大括号集合。

noglobstar

禁用**匹配多个文件夹名。

dot

允许模式匹配以句点开头的文件名，即使模式在该位置没有明确的句点。

注意，默认情况下，a/**/b将不会匹配a/.d/b，除非设置了dot。

noext

禁用+(a|b)这样的"extglob"风格模式。

nocase

执行不区分大小写的匹配。

nocaseMagicOnly

当与{nocase: true}一起使用时，创建不区分大小写的正则表达式，但保持字符串匹配部分不变。单独使用时没有效果。

当使用其他形式的不区分大小写匹配时，或者原始字符串表示在其他方面有用时，这个选项很有用。

nonull

当minimatch.match找不到匹配项时，如果设置了此选项，则返回包含模式本身的列表。未设置时，如果没有匹配项，则返回空列表。

magicalBraces

这只影响Minimatch.hasMagic方法的结果。

如果模式包含大括号展开，如a{b,c}d，但没有其他魔法字符，那么Minimatch.hasMagic()方法默认会返回false。设置此选项后，它会对大括号展开以及其他魔法glob字符返回true。

matchBase

如果设置，则不包含斜杠的模式将在路径包含斜杠时与路径的基名进行匹配。例如，a?b会匹配路径/xyz/123/acb，但不会匹配/xyz/acb/123。

nocomment

抑制将模式开头的#视为注释的行为。

nonegate

抑制将开头的!字符视为否定的行为。

flipNegate

对否定表达式返回与未否定时相同的结果。（即，匹配时为true，不匹配时为false。）

partial

将部分路径与模式进行比较。只要路径的现有部分不与模式矛盾，就会被视为匹配。这在应用程序中很有用，当你遍历文件夹结构，还没有完整路径，但想确保不会进入永远无法匹配的路径。

例如：

minimatch('/a/b', '/a/*/c/d', { partial: true }) // true，可能是 /a/b/c/d
minimatch('/a/b', '/**/d', { partial: true }) // true，可能是 /a/b/.../d
minimatch('/x/y/z', '/a/**/z', { partial: true }) // false，因为 x !== a

windowsPathsNoEscape

仅将\\用作路径分隔符，而不作为转义字符。如果设置，模式中的所有\\字符都会被替换为/。注意，这使得无法匹配包含字面glob模式字符的路径，但允许匹配在Windows平台上使用path.join()和path.resolve()构造的模式，模仿早期版本在Windows上的（有bug的！）行为。请谨慎使用，并注意关于Windows路径的警告。

出于遗留原因，如果options.allowWindowsEscape设置为精确值false，也会设置此选项。

windowsNoMagicRoot

当模式以UNC路径或驱动器字母开头，并且在nocase:true模式下，不将模式的根部分转换为不区分大小写的正则表达式，而是将它们保留为字符串。

当平台为win32且设置了nocase:true时，这是默认行为。

preserveMultipleSlashes

默认情况下，多个/字符（除了UNC路径开头的//，见上文"UNC路径"）被视为单个/。

也就是说，像a///b这样的模式会匹配文件路径a/b。

设置preserveMultipleSlashes: true来抑制这种行为。

optimizationLevel

一个数字，表示在解析和使用模式进行匹配之前应对其进行优化的级别。

当设置了noglobstar时，globstar部分**总是被转换为*，多个相邻的**部分会被转换为单个**（即，a/**/**/b会被视为a/**/b，因为在所有情况下它们是等价的）。

• 0 - 不进行进一步更改。在这种模式下，.和..在模式中保持不变，意味着它们在测试路径字符串中也必须出现在相同位置。例如，像a/*/../c这样的模式将匹配字符串a/b/../c，但不匹配字符串a/c。

• 1 - (默认) 移除双点..跟随非**、.、..或空''模式部分的情况。例如，模式./a/b/../*将转换为./a/*，因此它会匹配路径字符串./a/c，但不匹配路径字符串./a/b/../c。模式中的点和空路径部分会被保留。

• 2（或更高）- 更激进的优化，适用于文件遍历场景：

  • 移除双点..跟随非**、.或空''模式部分的情况。在安全的情况下，移除模式中的空和.部分（即，除了最后位置、第一位置，或以/开头的模式的第二个位置，因为这可能表示Windows上的UNC路径）。
  • 将包含<pre>/**/../<p>/<rest>的模式转换为等效的<pre>/{..,**}/<p>/<rest>，其中<p>是非.、..、**或空''的模式部分。
  • 去重存在**部分的模式，如果它不是最后的路径部分，并且其他部分相同。例如，{a/**/b,a/b}变为a/**/b，因为**可以匹配空路径部分。
  • 去重一个模式包含*，而另一个在相同位置包含非点、非**、.、..或''的模式。例如，a/{*,x}/b变为a/*/b，因为*可以匹配x。

  虽然这些优化提高了文件遍历用例（如glob）的性能（这也是本模块存在的原因），但在某些情况下，它可能无法匹配优化级别1或0本应匹配的字面字符串。

  具体来说，虽然Minimatch.match()方法会以相同的方式优化文件路径字符串，从而得到相同的匹配结果，但除非先使用minimatch.levelTwoFileOptimize()或类似方法处理路径字符串，否则使用Minimatch.makeRe()提供的正则表达式进行测试时会失败。

平台

当设置为win32时，将触发所有Windows特定行为（对UNC路径的特殊处理，以及在文件路径比较中将\视为分隔符）。

默认值为process.platform的值。

与其他fnmatch/glob实现的比较

虽然严格遵守现有标准是一个值得追求的目标，但minimatch和其他实现之间存在一些差异。有些是有意为之，有些则是不可避免的。

如果模式以!字符开头，则它被否定。设置nonegate标志可以抑制这种行为，并将开头的!字符视为普通字符。如果你希望模式以负向扩展glob模式（如!(a|B)）开头，这可能是相关的。模式开头的多个!字符将多次否定该模式。

如果模式以#开头，则它被视为注释，不会匹配任何内容。使用\#可以匹配行首的字面#，或设置nocomment标志来抑制这种行为。

默认支持双星号**，除非设置了noglobstar标志。这种支持方式类似于bsdglob和bash 4.1，其中**仅在作为路径部分的唯一内容时才具有特殊意义。也就是说，a/**/b会匹配a/x/y/b，但a/**b不会。

如果转义的模式没有匹配项，并且设置了nonull标志，则minimatch.match返回原始提供的模式，而不是解释字符转义。例如，minimatch.match([], "\\*a\\?")将返回"\\*a\\?"而不是"*a?"。这类似于在bash中设置nullglob选项，但它不会解析转义的模式字符。

如果未禁用大括号展开，则在对glob模式进行任何其他解释之前执行展开。因此，像+(a|{b),c)}这样在bash或zsh中无效的模式，会首先展开为+(a|b)和+(a|c)的集合，然后检查这些模式的有效性。由于这两个是有效的，因此继续进行匹配。

否定的扩展glob模式尽可能接近Bash语义处理，但某些否定扩展glob的情况在JavaScript正则表达式中极难表达。特别是，在bash中，否定模式<start>!(<pattern>*|)*将匹配任何不以<start><pattern>开头的内容。然而，<start>!(<pattern>*)*_会_匹配以<start><pattern>开头的路径，因为空字符串可以匹配否定部分。在这个库中，<start>!(<pattern>*|)*将_不_匹配任何以<start>开头的模式，这是由于正则表达式和bash路径展开在精确考虑哪些模式为"贪婪"方面存在差异。这可能是可以修复的，但会增加复杂性和性能成本，权衡下来似乎不值得追求。

注意，libc中的fnmatch(3)是一个非常简单的字符串比较匹配器，不会对斜杠做任何特殊处理。这个库设计用于glob搜索和文件遍历，因此对/进行了特殊处理。因此，在这个库中，foo*不会匹配foo/bar，尽管在fnmatch(3)中会匹配。