Creates a stream for reading Vinyl objects from the file system.
Note: BOMs (byte order marks) have no purpose in UTF-8 and will be removed from UTF-8 files read by src()
, unless disabled using the removeBOM
option.
const { src, dest } = require('gulp');
function copy() {
return src('input/*.js')
.pipe(dest('output/'));
}
exports.copy = copy;
src(globs, [options])
parameter | type | note |
---|---|---|
globs | string array |
Globs to watch on the file system. |
options | object | Detailed in Options below. |
A stream that can be used at the beginning or in the middle of a pipeline to add files based on the given globs.
When the globs
argument can only match one file (such as foo/bar.js
) and no match is found, throws an error with the message, "File not found with singular glob". To suppress this error, set the allowEmpty
option to true
.
When an invalid glob is given in globs
, throws an error with the message, "Invalid glob argument".
For options that accept a function, the passed function will be called with each Vinyl object and must return a value of another listed type.
name | type | default | note |
---|---|---|---|
buffer | boolean function |
true | When true, file contents are buffered into memory. If false, the Vinyl object's contents property will be a paused stream. Contents of large files may not be able to be buffered. Note: Plugins may not implement support for streaming contents. |
read | boolean function |
true | If false, files will be not be read and their Vinyl objects won't be writable to disk via .dest() . |
since | date timestamp function |
When set, only creates Vinyl objects for files that have been modified since the specified time. | |
removeBOM | boolean function |
true | When true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM. |
sourcemaps | boolean function |
false | If true, enables sourcemaps support on Vinyl objects created. Loads inline sourcemaps and resolves external sourcemap links. |
resolveSymlinks | boolean function |
true | When true, recursively resolves symbolic links to their targets. If false, preserves the symbolic links and sets the Vinyl object's symlink property to the original file's path. |
cwd | string | process.cwd() |
The directory that will be combined with any relative path to form an absolute path. Is ignored for absolute paths. Use to avoid combining globs with path.join() . This option is passed directly to glob-stream. |
base | string | Explicitly set the base property on created Vinyl objects. Detailed in API Concepts. This option is passed directly to glob-stream. |
|
cwdbase | boolean | false | If true, cwd and base options should be aligned. This option is passed directly to glob-stream. |
root | string | The root path that globs are resolved against. This option is passed directly to glob-stream. |
|
allowEmpty | boolean | false | When false, globs which can only match one file (such as foo/bar.js ) causes an error to be thrown if they don't find a match. If true, suppresses glob failures. This option is passed directly to glob-stream. |
uniqueBy | string function |
'path' |
Remove duplicates from the stream by comparing the string property name or the result of the function. Note: When using a function, the function receives the streamed data (objects containing cwd , base , path properties). |
dot | boolean | false | If true, compare globs against dot files, like .gitignore . This option is passed directly to node-glob. |
silent | boolean | true | When true, suppresses warnings from printing on stderr . Note: This option is passed directly to node-glob but defaulted to true instead of false . |
mark | boolean | false | If true, a / character will be appended to directory matches. Generally not needed because paths are normalized within the pipeline. This option is passed directly to node-glob. |
nosort | boolean | false | If true, disables sorting the glob results. This option is passed directly to node-glob. |
stat | boolean | false | If true, fs.stat() is called on all results. This adds extra overhead and generally should not be used. This option is passed directly to node-glob. |
strict | boolean | false | If true, an error will be thrown if an unexpected problem is encountered while attempting to read a directory. This option is passed directly to node-glob. |
nounique | boolean | false | When false, prevents duplicate files in the result set. This option is passed directly to node-glob. |
debug | boolean | false | If true, debugging information will be logged to the command line. This option is passed directly to node-glob. |
nobrace | boolean | false | If true, avoids expanding brace sets - e.g. {a,b} or {1..3} . This option is passed directly to node-glob. |
noglobstar | boolean | false | If true, treats double-star glob character as single-star glob character. This option is passed directly to node-glob. |
noext | boolean | false | If true, avoids matching extglob patterns - e.g. +(ab) . This option is passed directly to node-glob. |
nocase | boolean | false | If true, performs a case-insensitive match. Note: On case-insensitive file systems, non-magic patterns will match by default. This option is passed directly to node-glob. |
matchBase | boolean | false | If true and globs don't contain any / characters, traverses all directories and matches that glob - e.g. *.js would be treated as equivalent to **/*.js . This option is passed directly to node-glob. |
nodir | boolean | false | If true, only matches files, not directories. Note: To match only directories, end your glob with a / . This option is passed directly to node-glob. |
ignore | string array |
Globs to exclude from matches. This option is combined with negated globs . Note: These globs are always matched against dot files, regardless of any other settings. This option is passed directly to node-glob. |
|
follow | boolean | false | If true, symlinked directories will be traversed when expanding ** globs. Note: This can cause problems with cyclical links. This option is passed directly to node-glob. |
realpath | boolean | false | If true, fs.realpath() is called on all results. This may result in dangling links. This option is passed directly to node-glob. |
cache | object | A previously generated cache object - avoids some file system calls. This option is passed directly to node-glob. |
|
statCache | object | A previously generated cache of fs.Stat results - avoids some file system calls. This option is passed directly to node-glob. |
|
symlinks | object | A previously generated cache of symbolic links - avoids some file system calls. This option is passed directly to node-glob. |
|
nocomment | boolean | false | When false, treat a # character at the start of a glob as a comment. This option is passed directly to node-glob. |
Sourcemap support is built directly into src()
and dest()
, but is disabled by default. Enable it to produce inline or external sourcemaps.
Inline sourcemaps:
const { src, dest } = require('gulp');
const uglify = require('gulp-uglify');
src('input/**/*.js', { sourcemaps: true })
.pipe(uglify())
.pipe(dest('output/', { sourcemaps: true }));
External sourcemaps:
const { src, dest } = require('gulp');
const uglify = require('gulp-uglify');
src('input/**/*.js', { sourcemaps: true })
.pipe(uglify())
.pipe(dest('output/', { sourcemaps: '.' }));