From 69344858edb85e7c904621fa5d45782aa9825878 Mon Sep 17 00:00:00 2001 From: Blaine Bublitz Date: Thu, 17 Dec 2015 17:09:38 -0700 Subject: [PATCH] drastically improve docs --- README.md | 321 ++++++++++++++++++++++++++++++++++++++---------------- 1 file changed, 225 insertions(+), 96 deletions(-) diff --git a/README.md b/README.md index 690a7975..88d1f67a 100644 --- a/README.md +++ b/README.md @@ -1,160 +1,289 @@ -# vinyl-fs [![NPM version][npm-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Dependency Status][depstat-image]][depstat-url] -## Information - - - - -
Packagevinyl-fs
DescriptionVinyl adapter for the file system
Node Version>= 0.10
+

+ + + +

+ +# vinyl-fs + +[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Coveralls Status][coveralls-image]][coveralls-url] [![Gitter chat][gitter-image]][gitter-url] + +[Vinyl][vinyl] adapter for the file system. + +## What is Vinyl? + +[Vinyl][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][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][vinyl] can be used to describe files from all of these sources. + +## What is a Vinyl Adapter? + +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. ## Usage ```javascript var map = require('map-stream'); -var fs = require('vinyl-fs'); +var vfs = require('vinyl-fs'); var log = function(file, cb) { console.log(file.path); cb(null, file); }; -fs.src(['./js/**/*.js', '!./js/vendor/*.js']) +vfs.src(['./js/**/*.js', '!./js/vendor/*.js']) .pipe(map(log)) - .pipe(fs.dest('./output')); + .pipe(vfs.dest('./output')); ``` ## API -### src(globs[, opt]) -- Takes a glob string or an array of glob strings as the first argument. -- Globs are executed in order, so negations should follow positive globs. For example: + +### `src(globs[, options])` + +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 + +Globs are executed in order, so negations should follow positive globs. + +For example: ```js fs.src(['!b*.js', '*.js']) ``` -would not exclude any files, but this would +would not exclude any files, but the following would: ```js fs.src(['*.js', '!b*.js']) ``` -- Possible options for the second argument: - - cwd - Specify the working directory the folder is relative to. - - Default is `process.cwd()`. +#### Options + +##### `options.cwd` + +The working directory the folder is relative to. + +Type: `String` + +Default: `process.cwd()` + +##### `options.base` + +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`. - - base - Specify the folder relative to the cwd. This is used to determine the file names when saving in `.dest()`. - - Default is where the glob begins, if any. 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`. +##### `options.buffer` - - buffer - `true` or `false` if you want to buffer the file. - - Default value is `true`. - - `false` will make `file.contents` a paused Stream. +Whether or not you want to buffer the file contents into memory. Setting to `false` will make `file.contents` a paused Stream. - - read - `true` or `false` if you want the file to be read or not. Useful for stuff like `rm`ing files. - - Default value is `true`. - - `false` will disable writing the file to disk via `.dest()`. +Type: `Boolean` - - since - `Date` or `number` if you only want files that have been modified since the time specified. - - stripBOM - `true` or `false` if you want the BOM to be stripped on UTF-8 encoded files. - - Default value is `true`. +Default: `true` - - passthrough - `true` or `false` if you want a duplex stream which passes items through and emits globbed files. - - Default is `false`. +##### `options.read` - - sourcemaps - `true` or `false` if you want files to have sourcemaps enabled. - - Default is `false`. - - Will load inline sourcemaps and resolve sourcemap links from files - - Uses `gulp-sourcemaps` under the hood +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()`. - - followSymlinks - `true` if you want to recursively resolve symlinks to their targets; set to `false` to preserve them as symlinks. - - Default is `true`. - - `false` will make `file.symlink` equal the original symlink's target path. +Type: `Boolean` - - Any glob-related options are documented in [glob-stream] and [node-glob]. +Default: `true` - - Any through2-related options are documented in [through2] +##### `options.since` -- Returns a Readable stream by default, or a Duplex stream if the `passthrough` option is set to `true`. -- This stream emits matching [vinyl] File objects. +Only streams files that have been modified since the time specified. -_Note:_ UTF-8 BOM will be stripped from all UTF-8 files read with `.src`. +Type: `Date` or `Number` -### dest(folder[, opt]) -- Takes a folder path as the first argument. -- First argument can also be a function that takes in a file and returns a folder path. -- Possible options for the second argument: - - cwd - Specify the working directory the folder is relative to. - - Default is `process.cwd()`. +Default: `undefined` - - base - Specify the folder relative to the cwd. This is used to determine the file names when saving in `.dest()`. - - Default is the `cwd` resolves to the folder path. - - Can also be a function that takes in a file and returns a folder path. +##### `options.stripBOM` - - mode - Specify the mode the files should be created with. - - Default is the mode of the input file (file.stat.mode) if any. - - Default is the process mode if the input file has no mode property. +Causes the BOM to be stripped on UTF-8 encoded files. Set to `false` if you need the BOM for some reason. - - dirMode - Specify the mode the directory should be created with. - - Default is the process mode. +Type: `Boolean` - - overwrite - Specify if existing files with the same path should be overwritten or not. - - Default is `true`, to always overwrite existing files. - - Can also be a function that takes in a file and returns `true` or `false`. +Default: `true` - - sourcemaps - - - Default is `null` aka do not write sourcemaps. - - Uses `gulp-sourcemaps` under the hood - - Examples: - - Write as inline comments - - fs.dest('./', {sourcemaps: true}) - - Write as files in the same folder - - fs.dest('./', {
sourcemaps: {
path: '.'
}
}) - - Any other options are passed through to `gulp-sourcemaps` - - fs.dest('./', {
sourcemaps: {
path: '.',
addComment: false,
includeContent: false
}
}) +##### `options.passthrough` - - Any through2-related options are documented in [through2] +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. -- Returns a Readable/Writable stream. -- On write the stream will save the [vinyl] File to disk at the folder/cwd specified. -- After writing the file to disk, it will be emitted from the stream so you can keep piping these around. -- If the file has a `symlink` attribute specifying a target path, then a symlink will be created. -- The file will be modified after being written to this stream: +Type: `Boolean` + +Default: `false` + +##### `options.sourcemaps` + +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` + +##### `options.followSymlinks` - `true` if you want + +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` + +##### other + +Any glob-related options are documented in [glob-stream] and [node-glob]. +Any through2-related options are documented in [through2]. + +### `dest(folder[, options])` + +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. -### symlink(folder[, opt]) -- Takes a folder path as the first argument. -- First argument can also be a function that takes in a file and returns a folder path. -- Possible options for the second argument: - - cwd - Specify the working directory the folder is relative to. - - Default is `process.cwd()`. +#### Options + +##### `options.cwd` + +The working directory the folder is relative to. + +Type: `String` + +Default: `process.cwd()` + +##### `options.base` + +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. - - base - Specify the folder relative to the cwd. This is used to determine the file names when saving in `.dest()`. - - Default is the `cwd` resolves to the folder path. - - Can also be a function that takes in a file and returns a folder path. +Type: `String` or `Function` - - dirMode - Specify the mode the directory should be created with. - - Default is the process mode. +Default: The `cwd` resolved to the folder path. - - Any through2-related options are documented in [through2] +##### `options.mode` -- Returns a Readable/Writable stream. -- On write the stream will create a symbolic link (i.e. symlink) on disk at the folder/cwd specified. -- After creating the symbolic link, it will be emitted from the stream so you can keep piping these around. -- The file will be modified after being written to this stream: +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. + +##### `options.dirMode` + +The mode the directory should be created with. + +Type: `Number` + +Default: The process `mode`. + +##### `options.overwrite` + +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) + +##### `options.sourcemaps` + +Enables sourcemap support on files passed through the stream. Will write inline soucemaps if specified as `true`. Uses [gulp-sourcemaps] under the hood. + +Examples: + +```js +// 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) + +##### other + +Any through2-related options are documented in [through2]. + +### `symlink(folder[, options])` + +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. +#### Options + +##### `options.cwd` + +The working directory the folder is relative to. + +Type: `String` + +Default: `process.cwd()` + +##### `options.base` + +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. + +##### `options.dirMode` + +The mode the directory should be created with. + +Type: `Number` + +Default: The process mode. + +##### other + +Any through2-related options are documented in [through2]. + [glob-stream]: https://github.com/gulpjs/glob-stream +[gulp-sourcemaps]: https://github.com/floridoo/gulp-sourcemaps [node-glob]: https://github.com/isaacs/node-glob [gaze]: https://github.com/shama/gaze [glob-watcher]: https://github.com/wearefractal/glob-watcher [vinyl]: https://github.com/wearefractal/vinyl [through2]: https://github.com/rvagg/through2 + +[downloads-image]: http://img.shields.io/npm/dm/vinyl-fs.svg [npm-url]: https://www.npmjs.com/package/vinyl-fs [npm-image]: https://badge.fury.io/js/vinyl-fs.svg + [travis-url]: https://travis-ci.org/gulpjs/vinyl-fs [travis-image]: https://travis-ci.org/gulpjs/vinyl-fs.svg?branch=master -[coveralls-url]: https://coveralls.io/r/wearefractal/vinyl-fs -[coveralls-image]: https://img.shields.io/coveralls/wearefractal/vinyl-fs.svg?style=flat -[depstat-url]: https://david-dm.org/gulpjs/vinyl-fs -[depstat-image]: https://david-dm.org/gulpjs/vinyl-fs.svg + +[coveralls-url]: https://coveralls.io/r/gulpjs/vinyl-fs +[coveralls-image]: https://coveralls.io/repos/gulpjs/vinyl-fs/badge.svg + +[gitter-url]: https://gitter.im/gulpjs/gulp +[gitter-image]: https://badges.gitter.im/gulpjs/gulp.png