src()

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.

Usage

const { src, dest } = require('gulp');
function copy() {
return src('input/*.js')
.pipe(dest('output/'));
}
exports.copy = copy;

Signature

src(globs, [options])

Parameters

parametertypenote
globsstring
array
Globs to watch on the file system.
optionsobjectDetailed in Options below.

Returns

A stream that can be used at the beginning or in the middle of a pipeline to add files based on the given globs.

Errors

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".

Options

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.

nametypedefaultnote
bufferboolean
function
trueWhen true, file contents are buffered into memory. If false, the Vinyl object's contents property will be a paused stream. It may not be possible to buffer the contents of large files.
Note: Plugins may not implement support for streaming contents.
readboolean
function
trueIf false, files will be not be read and their Vinyl objects won't be writable to disk via .dest().
sincedate
timestamp
function
When set, only creates Vinyl objects for files modified since the specified time.
removeBOMboolean
function
trueWhen true, removes the BOM from UTF-8 encoded files. If false, ignores a BOM.
sourcemapsboolean
function
falseIf true, enables sourcemaps support on Vinyl objects created. Loads inline sourcemaps and resolves external sourcemap links.
resolveSymlinksboolean
function
trueWhen 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.
cwdstringprocess.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.
basestringExplicitly set the base property on created Vinyl objects. Detailed in API Concepts.
This option is passed directly to glob-stream.
cwdbasebooleanfalseIf true, cwd and base options should be aligned.
This option is passed directly to glob-stream.
rootstringThe root path that globs are resolved against.
This option is passed directly to glob-stream.
allowEmptybooleanfalseWhen 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.
uniqueBystring
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).
dotbooleanfalseIf true, compare globs against dot files, like .gitignore.
This option is passed directly to node-glob.
silentbooleantrueWhen true, suppresses warnings from printing on stderr.
Note: This option is passed directly to node-glob but defaulted to true instead of false.
markbooleanfalseIf 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.
nosortbooleanfalseIf true, disables sorting the glob results.
This option is passed directly to node-glob.
statbooleanfalseIf 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.
strictbooleanfalseIf 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.
nouniquebooleanfalseWhen false, prevents duplicate files in the result set.
This option is passed directly to node-glob.
debugbooleanfalseIf true, debugging information will be logged to the command line.
This option is passed directly to node-glob.
nobracebooleanfalseIf true, avoids expanding brace sets - e.g. {a,b} or {1..3}.
This option is passed directly to node-glob.
noglobstarbooleanfalseIf true, treats double-star glob character as single-star glob character.
This option is passed directly to node-glob.
noextbooleanfalseIf true, avoids matching extglob patterns - e.g. +(ab).
This option is passed directly to node-glob.
nocasebooleanfalseIf 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.
matchBasebooleanfalseIf 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.
nodirbooleanfalseIf true, only matches files, not directories.
Note: To match only directories, end your glob with a /.
This option is passed directly to node-glob.
ignorestring
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.
followbooleanfalseIf 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.
realpathbooleanfalseIf true, fs.realpath() is called on all results. This may result in dangling links.
This option is passed directly to node-glob.
cacheobjectA previously generated cache object - avoids some file system calls.
This option is passed directly to node-glob.
statCacheobjectA previously generated cache of fs.Stat results - avoids some file system calls.
This option is passed directly to node-glob.
symlinksobjectA previously generated cache of symbolic links - avoids some file system calls.
This option is passed directly to node-glob.
nocommentbooleanfalseWhen false, treat a # character at the start of a glob as a comment.
This option is passed directly to node-glob.

Sourcemaps

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: '.' }));