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.
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.
Segments and separators
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.
Here, the * is escaped, so it is treated as a literal instead of a wildcard character.
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
__filename global, or
process.cwd() for the same reasons.
const invalidGlob = path.join(__dirname, 'src/*.js');
Special character: * (single-star)
Matches any amount - including none - of characters within a single segment. Useful for globbing files within one directory.
This glob will match files like
index.js, but not files like
Special character: ** (double-star)
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.
Here, the glob is appropriately restricted to the
scripts/ directory. It will match files like
In the previous example, if
scripts/ wasn't prefixed, all dependencies in
node_modules or other directories would also be matched.
Special character: ! (negative)
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.
If any non-negative globs follow a negative, nothing will be removed from the later set of matches.
['script/**/*.js', '!scripts/vendor/', 'scripts/vendor/react.js']
Negative globs can be used as an alternative for restricting double-star globs.
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.
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
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.