Vinyladapter for the file system.
Vinylis a very simple metadata object that describes a file. When you think of a file, two attributes come to mind:path
andcontents
.These are the main attributes on aVinylobject. 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.Vinylcan 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 we call a "Vinyl adapter". A Vinyl adapter simply exposes asrc(globs)
and adest(folder)
method. Each return a stream. Thesrc
stream produces Vinyl objects, and thedest
stream consumes Vinyl objects. Vinyl adapters can expose extra methods that might be specific to their input/output medium, such as thesymlink
methodvinyl-fs
provides.
varmap=require('map-stream');
varvfs=require('vinyl-fs');
varlog=function(file,cb){
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 ofvinylFile
objects.
Note: UTF-8 BOM will be removed 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*','*']);
would not exclude any files, but the following would exclude all files starting with "b":
fs.src(['*','!b*']);
- Values passed to the options must be of the expected type, otherwise they will be ignored.
- All options can be passed a function instead of a value. The function will be called with thevinyl
File
object as its only argument and must return a value of the expected type for that option.
Whether or not you want to buffer the file contents into memory. Setting tofalse
will makefile.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 tofalse
will makefile.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
orNumber
Default:undefined
Causes the BOM to be removed on UTF-8 encoded files. Set tofalse
if you need the BOM for some reason.
Type:Boolean
Default:true
Optionally transcode from the given encoding. The default is'utf8'
.We use
iconv-lite,please refer to its Wiki for a list of supported encodings. You
can set this tofalse
to avoid any transcoding, and effectively just pass
around raw binary data.
Type:String
orBoolean
Default:'utf8'
Enables sourcemap support on files passed through the stream. Will load inline sourcemaps and resolve sourcemap links from files.
Type:Boolean
Default:false
Whether or not to recursively resolve symlinks to their targets. Set tofalse
to preserve them as symlinks and makefile.symlink
equal the original symlink's target path.
Type:Boolean
Default:true
Whether or not you want globs to match on dot files (e.g..gitignore
).
Note: This option is not resolved from a function because it is passed verbatim to anymatch.
Type:Boolean
Default:false
Any glob-related options are documented inglob-streamandanymatchand are forwarded verbatim.
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 eachvinylFile
object and must return a folder path.
Returns a stream that acceptsvinylFile
objects, writes them to disk at the folder/cwd specified, and passes them downstream so you can keep piping these around.
Once the file is written to disk, an attempt is made to determine if thestat.mode
,stat.mtime
andstat.atime
of thevinylFile
object differ from the file on the filesystem.
If they differ and the running process owns the file, the corresponding filesystem metadata is updated.
If they don't differ or the process doesn't own the file, the attempt is skipped silently.
This functionality is disabled on Windows operating systems or any other OS that doesn't supportprocess.getuid
orprocess.geteuid
in node. This is due to Windows having very unexpected results through usage offs.fchmod
andfs.futimes
.
Note: Thefs.futimes()
method internally convertsstat.mtime
andstat.atime
timestamps to seconds; this division by1000
may cause some loss of precision in 32-bit Node.js.
If the file has asymlink
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
,andpath
will be overwritten to match the folder.stat
will be updated to match the file on the filesystem.contents
will have it's position reset to the beginning if it is a stream.
- Values passed to the options must be of the expected type, otherwise they will be ignored.
- All options can be passed a function instead of a value. The function will be called with thevinyl
File
object as its only argument and must return a value of the expected type for that option.
The working directory the folder is relative to.
Type:String
Default:process.cwd()
The mode the files should be created with. This option is only resolved if thevinylFile
is not symbolic.
Type:Number
Default: Themode
of the input file (file.stat.mode
) if any, or the process mode if the input file has nomode
property.
The mode directories should be created with.
Type:Number
Default: The processmode
.
Whether or not existing files with the same path should be overwritten.
Type:Boolean
Default:true
(always overwrite existing files)
Whether or not new data should be appended after existing file contents (if any).
Type:Boolean
Default:false
(always replace existing contents, if any)
Optionally transcode to the given encoding. The default is'utf8'
.We use
iconv-lite,please refer to its Wiki for a list of supported encodings. You
can set this tofalse
to avoid any transcoding, and effectively just pass
around raw binary data.
Type:String
orBoolean
Default:'utf8'
.
Enables sourcemap support on files passed through the stream. Will write inline soucemaps if specified astrue
.
Specifying aString
path will write external sourcemaps at the given path.
Examples:
// Write as inline comments
vfs.dest('./',{sourcemaps:true});
// Write as files in the same folder
vfs.dest('./',{sourcemaps:'.'});
Type:Boolean
orString
Default:undefined
(do not write sourcemaps)
When creating a symlink, whether or not the created symlink should be relative. Iffalse
,the symlink will be absolute.
Note: This option will be ignored if ajunction
is being created, as they must be absolute.
Type:Boolean
Default:false
When creating a symlink, whether or not a directory symlink should be created as ajunction
.
This option is only relevant on Windows and ignored elsewhere. Please refer to theSymbolic Links on Windowssection below.
Type:Boolean
Default:true
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 eachvinylFile
object and must return a folder path.
Returns a stream that acceptsvinylFile
objects, creates 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
,andpath
will be overwritten to match the folder.stat
will be updated to match the symlink on the filesystem.contents
will be set tonull
.symlink
will be added or replaced to be the original path.
Note: On Windows, directory links are created using Junctions by default. Use theuseJunctions
option to disable this behavior.
- Values passed to the options must be of the expected type, otherwise they will be ignored.
- All options can be passed a function instead of a value. The function will be called with thevinyl
File
object as its only argument and must return a value of the expected type for that option.
The working directory the folder is relative to.
Type:String
Default:process.cwd()
The mode directories should be created with.
Type:Number
Default: The process mode.
Whether or not existing files with the same path should be overwritten.
Type:Boolean
Default:true
(always overwrite existing files)
Whether or not the created symlinks should be relative. Iffalse
,the symlink will be absolute.
Note: This option will be ignored if ajunction
is being created, as they must be absolute.
Type:Boolean
Default:false
When creating a symlink, whether or not a directory symlink should be created as ajunction
.
This option is only relevant on Windows and ignored elsewhere. Please refer to theSymbolic Links on Windowssection below.
Type:Boolean
Default:true
When creating symbolic links on Windows, we pass atype
argument to Node's
fs
module which specifies the kind of target we link to (one of'file'
,
'dir'
or'junction'
). Specifically, this will be'file'
when the target
is a regular file,'junction'
if the target is a directory, or'dir'
if
the target is a directory and the user overrides theuseJunctions
option
default.
However, if the user tries to make a "dangling" link (pointing to a non-existent
target) we won't be able to determine automatically which type we should use.
In these cases,vinyl-fs
will behave slightly differently depending on
whether the dangling link is being created viasymlink()
or viadest()
.
For dangling links created viasymlink()
,the incoming vinyl represents the
target and so we will look to its stats to guess the desired type. In
particular, ifisDirectory()
returns false then we'll create a'file'
type
link, otherwise we will create a'junction'
or a'dir'
type link depending
on the value of theuseJunctions
option.
For dangling links created viadest()
,the incoming vinyl represents the link -
typically read off disk viasrc()
with theresolveSymlinks
option set to
false. In this case, we won't be able to make any reasonable guess as to the
type of link and we default to using'file'
,which may cause unexpected behavior
if you are creating a "dangling" link to a directory. It is advised to avoid this
scenario.
MIT