bricks-cli
Version:
Command line tool for developing ambitious ember.js apps
65 lines (64 loc) • 10.3 kB
JSON
{
"name": "fs-extra",
"version": "0.8.1",
"description": "fs-extra contains methods that aren't included in the vanilla Node.js fs package. Such as mkdir -p, cp -r, and rm -rf.",
"homepage": "https://github.com/jprichardson/node-fs-extra",
"repository": {
"type": "git",
"url": "https://github.com/jprichardson/node-fs-extra"
},
"keywords": [
"fs",
"file",
"file system",
"copy",
"directory",
"extra",
"mkdirp",
"mkdir",
"mkdirs",
"recursive",
"json",
"read",
"write",
"extra",
"delete",
"remove",
"touch",
"create",
"text",
"output"
],
"author": {
"name": "JP Richardson",
"email": "jprichardson@gmail.com"
},
"licenses": [
{
"type": "MIT",
"url": "http://github.com/jprichardson/node-fs-extra/raw/master/LICENSE"
}
],
"dependencies": {
"ncp": "~0.4.2",
"mkdirp": "0.3.x",
"jsonfile": "~1.1.0",
"rimraf": "~2.2.0"
},
"devDependencies": {
"mocha": "*",
"path-extra": "0.0.x",
"testutil": "~0.5.0"
},
"main": "./lib/index",
"scripts": {
"test": "mocha test"
},
"readme": "\nNode.js: fs-extra\n=================\n\n[](http://travis-ci.org/jprichardson/node-fs-extra)\n\nThis module adds a few extra file system methods that aren't included in the native `fs` module. It is a drop in replacement for `fs`.\n\n\n\nWhy?\n----\n\nI got tired of including `mkdirp`, `rimraf`, and `cp -r` in most of my projects. \n\n\n\n\nInstallation\n------------\n\n npm install --save fs-extra\n\n\n\nUsage\n-----\n\n`fs-extra` is a drop in replacement for native `fs`. All methods in `fs` are unmodified and attached to `fs-extra`.\n\nYou don't ever need to include the original `fs` module again:\n\n```javascript\nvar fs = require('fs') //this is no longer necessary\n```\n\nyou can now do this:\n\n```javascript\nvar fs = require('fs-extra'); //var fs = require('fs')\n```\n\nor if you prefer to make it clear that you're using `fs-extra` and not `fs`, you may want \nto do this:\n\n```javascript\n//var fs = require('fs')\nvar fse = require('fs-extra')\n```\n\nyou can also keep, both, but it's redundant:\n\n```javascript\nvar fs = require('fs')\n , fse = require('fs-extra')\n```\n\n\n\nMethods\n-------\n\n**NOTE:** You can still use the native Node.js methods. They are copied over to `fs-extra`.\n\n\n### copy(src, dest, [filter], callback)\n\nCopy a file or directory. The directory can have contents. Like `cp -r`. There isn't a synchronous version implemented yet.\n\nSync: `copySync()`\n\n\nExamples:\n\n```javascript\nvar fs = require('fs-extra');\n\nfs.copy('/tmp/myfile', '/tmp/mynewfile', function(err){\n if (err) return console.error(err);\n\n console.log(\"success!\")\n}); //copies file\n\nfs.copy('/tmp/mydir', '/tmp/mynewdir', function(err){\n if (err) return console.error(err);\n \n console.log(\"success!\")\n}); //copies directory, even if it has subdirectories or files\n```\n\n\n### createFile(file, callback) \n\nCreates a file. If the file that is requested to be created is in directories that do not exist, these directories are created. If the file already exists, it is **NOT MODIFIED**.\n\nSync: `createFileSync()`\n\n\nExample:\n\n```javascript\nvar fs = require('fs-extra')\n\nvar file = '/tmp/this/path/does/not/exist/file.txt'\n\nfs.createFile(file, function(err) {\n console.log(err); //null\n //file has now been created, including the directory it is to be placed in\n})\n```\n\n\n\n### mkdirs(dir, callback) \n\nCreates a directory. If the parent hierarchy doesn't exist, it's created. Like `mkdir -p`.\n\nAlias: `mkdirp()`\n\nSync: `mkdirsSync()` / `mkdirpSync()`\n\n\nExamples:\n\n```javascript\nvar fs = require('fs-extra');\n\nfs.mkdirs('/tmp/some/long/path/that/prob/doesnt/exist', function(err){\n if (err) return console.error(err);\n \n console.log(\"success!\")\n});\n\nfs.mkdirsSync('/tmp/another/path');\n```\n\n\n### outputFile(file, data, callback)\n\nAlmost the same as `writeFile`, except that if the directory does not exist, it's created.\n\nSync: `outputFileSync()`\n\n\nExample:\n\n```javascript\nvar fs = require('fs-extra')\nvar file = '/tmp/this/path/does/not/exist/file.txt'\n\nfs.outputFile(file, 'hello!', function(err) {\n console.log(err); //null\n\n fs.readFile(file, 'utf8', function(err, data) {\n console.log(data); //hello!\n })\n})\n```\n\n\n\n### outputJson(file, data, callback)\n\nAlmost the same as `writeJson`, except that if the directory does not exist, it's created.\n\nAlias: `outputJSON()\n\nSync: `outputJsonSync()`, `outputJSONSync()`\n\n\nExample:\n\n```javascript\nvar fs = require('fs-extra')\nvar file = '/tmp/this/path/does/not/exist/file.txt'\n\nfs.outputJson(file, {name: 'JP'}, function(err) {\n console.log(err); //null\n\n fs.readJson(file, function(err, data) {\n console.log(data.name); //'JP\n })\n})\n```\n\n\n\n### readJson(file, [options], callback) \n\nReads a JSON file and then parses it into an object. `options` are the same that you'd pass to `fs.readFile`.\n\nAlias: `readJSON()`\n\nSync: `readJsonSync()`, `readJSONSync()`\n\n\nExample:\n\n```javascript\nvar fs = require('fs-extra');\n\nfs.readJson('./package.json', function(err, packageObj) {\n console.log(packageObj.version); //0.1.3\n});\n```\n\n\n### remove(dir, callback)\n\nRemoves a file or directory. The directory can have contents. Like `rm -rf`.\n\nAlias: `delete()`\n\nSync: `removeSync()` / `deleteSync()`\n\n\nExamples:\n\n```javascript\nvar fs = require('fs-extra');\n\nfs.remove('/tmp/myfile', function(err){\n if (err) return console.error(err);\n \n console.log(\"success!\")\n});\n\nfs.removeSync('/home/jprichardson'); //I just deleted my entire HOME directory. \n```\n\n\n\n### writeJson(file, object, [options], callback) \n\nWrites an object to a JSON file. `options` are the same that you'd pass to `fs.readFile`.\n\nAlias: `writeJSON()`\n\nSync: `writeJsonSync()`, `writeJSONSync()`\n\nExample:\n\n```javascript\nvar fs = require('fs-extra');\nfs.writeJson('./package.json', {name: 'fs-extra'}, function(err){\n console.log(err);\n});\n```\n\n\n\nRoadmap to 1.0.0\n-----------------\n\nThis contains items that I'm considering doing. I'd love community feedback.\n\n* File system walker. I really like this one: https://github.com/daaku/nodejs-walker ... this might be adding too much. Thoughts?\n* File/directory tree watcher. There are quite a few. ... this also might be adding too much. I like this one: https://github.com/paulmillr/chokidar but I don't like that it's written in CoffeeScript. Thoughts?\n* Method to move files.\n* Thinking about moving `rimraf`, `ncp`, and `mkdirps` code into this library. I'd like fs-extra to be a stable library that module authors\ncan depend upon. A bunch of other dependencies kinda sucks for modules/libraries. (I'm leaning against this now.)\n* Change documentation to use the `fse` prefix instead of `fs`. This may encourage people to start using `fse` as a prefix and hence make their code clearer that they're not using the native `fs`. I'm very undecided on this one since `fs-extra` is a drop in replacement for the native `fs`. (I'm leaning against this now.)\n\n\n\nNaming\n------\n\nI put a lot of thought into the naming of these functions. Inspired by @coolaj86's request. So he deserves much of the credit for raising the issue. See discussion(s) here:\n\n* https://github.com/jprichardson/node-fs-extra/issues/2\n* https://github.com/flatiron/utile/issues/11\n* https://github.com/ryanmcgrath/wrench-js/issues/29\n* https://github.com/substack/node-mkdirp/issues/17\n\nFirst, I believe that in as many cases as possible, the [Node.js naming schemes](http://nodejs.org/api/fs.html) should be chosen. However, there are problems with the Node.js own naming schemes.\n\nFor example, `fs.readFile()` and `fs.readdir()`: the **F** is capitalized in *File* and the **d** is not capitalized in *dir*. Perhaps a bit pedantic, but they should still be consistent. Also, Node.js has chosen a lot of POSIX naming schemes, which I believe is great. See: `fs.mkdir()`, `fs.rmdir()`, `fs.chown()`, etc.\n\nWe have a dilemma though. How do you consistently name methods that perform the following POSIX commands: `cp`, `cp -r`, `mkdir -p`, and `rm -rf`?\n\nMy perspective: when in doubt, err on the side of simplicity. A directory is just a hierarchical grouping of directories and files. Consider that for a moment. So when you want to copy it or remove it, in most cases you'll want to copy or remove all of its contents. When you want to create a directory, if the directory that it's suppose to be contained in does not exist, then in most cases you'll want to create that too. \n\nSo, if you want to remove a file or a directory regardless of whether it has contents, just call `fs.remove(path)` or its alias `fs.delete(path)`. If you want to copy a file or a directory whether it has contents, just call `fs.copy(source, destination)`. If you want to create a directory regardless of whether its parent directories exist, just call `fs.mkdirs(path)` or `fs.mkdirp(path)`. \n\n\nCredit\n------\n\n`fs-extra` wouldn't be possible without using the modules from the following authors:\n\n- [Isaac Shlueter](https://github.com/isaacs)\n- [Charlie McConnel](https://github.com/avianflu)\n- [James Halliday](https://github.com/substack)\n\n\nContributions\n-------------\n\nIf you want to contribute, please add a test if you can. Also, don't change the version in `package.json`.\n\n\n### Contributors\n\n- [JP Richardson](https://github.com/jprichardson)\n- [Mike McNeil](https://github.com/mikermcneil)\n- [Ian Crowther](https://github.com/iancrowther)\n- [Stephen Mathieson](https://github.com/stephenmathieson)\n- [Srirangan](https://github.com/Srirangan)\n- [Uli Köhler](https://github.com/ulikoehler)\n- `<your name here>`\n\n\n\n\nLicense\n-------\n\n\nLicensed under MIT\n\nCopyright (c) 2011-2013 JP Richardson\n\n[1]: http://nodejs.org/docs/latest/api/fs.html \n\n\n[jsonfile]: https://github.com/jprichardson/node-jsonfile\n\n\n\n\n\n",
"readmeFilename": "README.md",
"bugs": {
"url": "https://github.com/jprichardson/node-fs-extra/issues"
},
"_id": "fs-extra@0.8.1",
"_from": "fs-extra@^0.8.1"
}