0
# Main Matching
1

2
Core functionality for filtering arrays of strings against glob patterns with support for negation, advanced patterns, and extensive configuration options.
3

4
## Capabilities
5

6
### Main Export Function
7

8
The primary micromatch function that filters strings from a list using one or more glob patterns.
9

10
```javascript { .api }
11
/**
12
 * Returns an array of strings that match one or more glob patterns
13
 * @param {string|string[]} list - List of strings to match
14
 * @param {string|string[]} patterns - One or more glob patterns to use for matching
15
 * @param {object} options - See available options for changing how matches are performed
16
 * @returns {string[]} Returns an array of matches
17
 */
18
function micromatch(list, patterns, options);
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
const micromatch = require('micromatch');
25

26
// Basic matching
27
console.log(micromatch(['foo', 'bar', 'baz', 'qux'], ['f*', 'b*']));
28
//=> ['foo', 'bar', 'baz']
29

30
// Negation patterns
31
console.log(micromatch(['foo', 'bar', 'baz', 'qux'], ['*', '!b*']));
32
//=> ['foo', 'qux']
33

34
// Multiple patterns with options
35
const files = ['src/app.js', 'test/app.test.js', 'docs/readme.md'];
36
console.log(micromatch(files, '**/*.js', { dot: true }));
37
//=> ['src/app.js', 'test/app.test.js']
38
```
39

40
### Match Method (Alias)
41

42
Backwards compatibility alias for the main micromatch function.
43

44
```javascript { .api }
45
/**
46
 * Alias for micromatch() - backwards compatibility
47
 * @param {string|string[]} list - List of strings to match
48
 * @param {string|string[]} patterns - One or more glob patterns
49
 * @param {object} options - See available options
50
 * @returns {string[]} Returns an array of matches
51
 */
52
micromatch.match = micromatch;
53
```
54

55
## Pattern Features
56

57
### Glob Patterns
58

59
Supports standard glob patterns:
60

61
- `*` - Matches any number of characters (except path separators)
62
- `?` - Matches a single character
63
- `[abc]` - Matches any character in the set
64
- `[a-z]` - Matches any character in the range
65
- `**` - Matches directories recursively (globstar)
66

67
### Extended Patterns (Extglobs)
68

69
When extglobs are enabled (default):
70

71
- `!(pattern)` - Negation
72
- `?(pattern)` - Zero or one occurrence
73
- `+(pattern)` - One or more occurrences
74
- `*(pattern)` - Zero or more occurrences
75
- `@(pattern)` - Exactly one occurrence
76

77
### Brace Expansion
78

79
Supports brace patterns like:
80

81
- `{a,b,c}` - Alternation
82
- `{1..10}` - Numeric ranges
83
- `{a..z}` - Character ranges
84

85
### Negation
86

87
Leading `!` in patterns negates the match:
88

89
```javascript
90
// Exclude .test.js files
91
micromatch(files, ['**/*.js', '!**/*.test.js']);
92
```
93

94
## Error Handling
95

96
- Throws `Error` when `failglob: true` option is set and no matches are found
97
- Returns empty array `[]` when no matches found (default behavior)
98
- Supports `nonull` and `nullglob` options for controlling empty result behavior
99

100
## Performance Notes
101

102
- Optimized for performance with fast-path implementations for common patterns
103
- Lazy compilation of regular expressions
104
- Efficient handling of large file lists
105
- Can disable expensive features via options (e.g., `noextglob`, `nobrace`)