vinyl-fs

Vinyl adapter for the file system

vinyl-fs

Vinyl adapter for the file system.

Vinyl is a very simple metadata object that describes a file. When you think of a file, two attributes come to mind: path and contents. These are the main attributes on a Vinyl object. A file does not necessarily represent something on your computer’s file system. You have files on S3, FTP, Dropbox, Box, CloudThingly.io and other services. Vinyl can be used to describe files from all of these sources.

While Vinyl provides a clean way to describe a file, we now need a way to access these files. Each file source needs what I call a "Vinyl adapter". A Vinyl adapter simply exposes a src(globs) and a dest(folder) method. Each return a stream. The src stream produces Vinyl objects, and the dest stream consumes Vinyl objects. Vinyl adapters can expose extra methods that might be specific to their input/output medium, such as the symlink method vinyl-fs provides.

var map = require('map-stream');
var vfs = require('vinyl-fs');
 
var log = function(filecb) {
  console.log(file.path);
  cb(null, file);
};
 
vfs.src(['./js/**/*.js', '!./js/vendor/*.js'])
  .pipe(map(log))
  .pipe(vfs.dest('./output'));

Takes a glob string or an array of glob strings as the first argument and an options object as the second. Returns a stream of vinyl File objects.

Note: UTF-8 BOM will be stripped from all UTF-8 files read with .src unless disabled in the options.

Globs are executed in order, so negations should follow positive globs.

For example:

fs.src(['!b*.js', '*.js'])

would not exclude any files, but the following would:

fs.src(['*.js', '!b*.js'])

The working directory the folder is relative to.

Type: String

Default: process.cwd()

The folder relative to the cwd. This is used to determine the file names when saving in .dest().

Type: String

Default: The part of the path before the glob (if any) begins. For example, path/to/**/*.js would resolve to path/to. If there is no glob (i.e. a file path with no pattern), then the dirname of the path is used. For example, path/to/some/file.js would resolve to path/to/some.

Whether or not you want to buffer the file contents into memory. Setting to false will make file.contents a paused Stream.

Type: Boolean

Default: true

Whether or not you want the file to be read at all. Useful for stuff like removing files. Setting to false will make file.contents null and will disable writing the file to disk via .dest().

Type: Boolean

Default: true

Only streams files that have been modified since the time specified.

Type: Date or Number

Default: undefined

Causes the BOM to be stripped on UTF-8 encoded files. Set to false if you need the BOM for some reason.

Type: Boolean

Default: true

Allows .src to be used in the middle of a pipeline (using a duplex stream) which passes through all objects received and adds all files globbed to the stream.

Type: Boolean

Default: false

Enables sourcemap support on files passed through the stream. Will load inline sourcemaps and resolve sourcemap links from files. Uses gulp-sourcemaps under the hood.

Type: Boolean

Default: false

Whether or not to recursively resolve symlinks to their targets. Setting to false to preserve them as symlinks and make file.symlink equal the original symlink's target path.

Type: Boolean

Default: true

Any glob-related options are documented in glob-stream and node-glob. Any through2-related options are documented in through2.

Takes a folder path string or a function as the first argument and an options object as the second. If given a function, it will be called with each vinyl File object and must return a folder path. Returns a stream that accepts vinyl File objects, writes them to disk at the folder/cwd specified, and passes them downstream so you can keep piping these around.

If the file has a symlink attribute specifying a target path, then a symlink will be created.

Note: The file will be modified after being written to this stream.

  • cwd, base, and path will be overwritten to match the folder.
  • stat.mode will be overwritten if you used a mode parameter.
  • contents will have it's position reset to the beginning if it is a stream.

The working directory the folder is relative to.

Type: String

Default: process.cwd()

The folder relative to the cwd. This is used to determine the file names when saving in .dest(). Can also be a function that takes in a file and returns a folder path.

Type: String or Function

Default: The cwd resolved to the folder path.

The mode the files should be created with.

Type: Number

Default: The mode of the input file (file.stat.mode) if any, or the process mode if the input file has no mode property.

The mode the directory should be created with.

Type: Number

Default: The process mode.

Whether or not existing files with the same path should be overwritten. Can also be a function that takes in a file and returns true or false.

Type: Boolean or Function

Default: true (always overwrite existing files)

Enables sourcemap support on files passed through the stream. Will write inline soucemaps if specified as true. Uses gulp-sourcemaps under the hood.

Examples:

// Write as inline comments 
vfs.dest('./', {
  sourcemaps: true
});
 
// Write as files in the same folder 
vfs.dest('./', {
  sourcemaps: {
    path: '.'
  }
});
 
// Any other options are passed through to [gulp-sourcemaps] 
vfs.dest('./', {
  sourcemaps: {
    path: '.',
    addComment: false,
    includeContent: false
  }
});

Type: Boolean or Object

Default: undefined (do not write sourcemaps)

Any through2-related options are documented in through2.

Takes a folder path string or a function as the first argument and an options object as the second. If given a function, it will be called with each vinyl File object and must return a folder path. Returns a stream that accepts vinyl File objects, create a symbolic link (i.e. symlink) at the folder/cwd specified, and passes them downstream so you can keep piping these around.

Note: The file will be modified after being written to this stream.

  • cwd, base, and path will be overwritten to match the folder.

The working directory the folder is relative to.

Type: String

Default: process.cwd()

The folder relative to the cwd. This is used to determine the file names when saving in .symlink(). Can also be a function that takes in a file and returns a folder path.

Type: String or Function

Default: The cwd resolved to the folder path.

The mode the directory should be created with.

Type: Number

Default: The process mode.

Any through2-related options are documented in through2.