Skip to content

Commit f8cafa0

Browse files
janiceilenephated
authored andcommitted
Docs: Add "Explaining Globs" documentation
1 parent ad8b568 commit f8cafa0

File tree

1 file changed

+88
-0
lines changed

1 file changed

+88
-0
lines changed
+88
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,88 @@
1+
<!-- front-matter
2+
id: explaining-globs
3+
title: Explaining Globs
4+
hide_title: true
5+
sidebar_label: Explaining Globs
6+
-->
7+
8+
# Explaining Globs
9+
10+
A glob is a string of literal and/or wildcard characters used to match filepaths. Globbing is the act of locating files on a filesystem using one or more globs.
11+
12+
The `src()` method expects a single glob string or an array of globs to determine which files your pipeline will operate on. At least one match must be found for your glob(s) otherwise `src()` will error. When an array of globs is used, they are matched in array order - especially useful for negative globs.
13+
14+
## Segments and separators
15+
16+
A segment is everything between separators. The separator in a glob is always the `/` character - regardless of the operating system - even in Windows where the path separator is `\\`. In a glob, `\\` is reserved as the escape character.
17+
18+
Here, the * is escaped, so it is treated as a literal instead of a wildcard character.
19+
```js
20+
'glob_with_uncommon_\\*_character.js'
21+
```
22+
23+
Avoid using Node's `path` methods, like `path.join`, to create globs. On Windows, it produces an invalid glob because Node uses `\\` as the separator. Also avoid the `__dirname` global, `__filename` global, or `process.cwd()` for the same reasons.
24+
25+
```js
26+
const invalidGlob = path.join(__dirname, 'src/*.js');
27+
```
28+
29+
## Special character: * (single-star)
30+
31+
Matches any amount - including none - of characters within a single segment. Useful for globbing files within one directory.
32+
33+
This glob will match files like `index.js`, but not files like `scripts/index.js` or `scripts/nested/index.js`
34+
```js
35+
'*.js'
36+
```
37+
38+
## Special character: ** (double-star)
39+
40+
Matches any amount - including none - of characters across segments. Useful for globbing files in nested directories. Make sure to appropriately restrict your double-star globs, to avoid matching large directories unnecessarily.
41+
42+
Here, the glob is appropriately restricted to the `scripts/` directory. It will match files like `scripts/index.js`, `scripts/nested/index.js`, and `scripts/nested/twice/index.js`.
43+
44+
```js
45+
'scripts/**/*.js'
46+
```
47+
48+
<small>In the previous example, if `scripts/` wasn't prefixed, all dependencies in `node_modules` or other directories would also be matched.</small>
49+
50+
## Special character: ! (negative)
51+
52+
Since globs are matched in array order, a negative glob must follow at least one non-negative glob in an array. The first finds a set of matches, then the negative glob removes a portion of those results. These are most performant when they only include literal characters.
53+
54+
```js
55+
['script/**/*.js', '!scripts/vendor/']
56+
```
57+
58+
If any non-negative globs follow a negative, nothing will be removed from the later set of matches.
59+
60+
```js
61+
['script/**/*.js', '!scripts/vendor/', 'scripts/vendor/react.js']
62+
```
63+
64+
Negative globs can be used as an alternative for restricting double-star globs.
65+
66+
```js
67+
['**/*.js', '!node_modules/']
68+
```
69+
70+
<small>In the previous example, if the negative glob was `!node_modules/**/*.js`, every match would have to be compared against the negative glob, which would be extremely slow.</small>
71+
72+
## Overlapping globs
73+
74+
Two or more globs that (un)intentionally match the same file are considered overlapping. When overlapping globs are used within a single `src()`, gulp does its best to remove the duplicates, but doesn't attempt to deduplicate across separate `src()` calls.
75+
76+
## Advanced resources
77+
78+
Most of what you'll need to work with globs in gulp is covered here. If you'd like to get more in depth, here are a few resources.
79+
80+
* [Micromatch Documentation][micromatch-docs]
81+
* [node-glob's Glob Primer][glob-primer-docs]
82+
* [Begin's Globbing Documentation][begin-globbing-docs]
83+
* [Wikipedia's Glob Page][wikipedia-glob]
84+
85+
[micromatch-docs]: https://github.com/micromatch/micromatch
86+
[glob-primer-docs]: https://github.com/isaacs/node-glob#glob-primer
87+
[begin-globbing-docs]: https://github.com/begin/globbing#what-is-globbing
88+
[wikipedia-glob]: https://en.wikipedia.org/wiki/Glob_(programming)

0 commit comments

Comments
 (0)