diff --git a/docs/copy-sync.md b/docs/copy-sync.md index 3fca1330..3e5243cc 100644 --- a/docs/copy-sync.md +++ b/docs/copy-sync.md @@ -1,6 +1,6 @@ # copySync(src, dest[, options]) -Copy a file or directory. The directory can have contents. Like `cp -r`. +Copy a file or directory. The directory can have contents. - `src` `<String>` Note that if `src` is a directory it will copy everything inside of this directory, not the entire directory itself (see [issue #537](https://github.com/jprichardson/node-fs-extra/issues/537)). - `dest` `<String>` Note that if `src` is a file, `dest` cannot be a directory (see [issue #323](https://github.com/jprichardson/node-fs-extra/issues/323)). diff --git a/docs/copy.md b/docs/copy.md index 4add5684..0e66da58 100644 --- a/docs/copy.md +++ b/docs/copy.md @@ -1,6 +1,6 @@ # copy(src, dest[, options][, callback]) -Copy a file or directory. The directory can have contents. Like `cp -r`. +Copy a file or directory. The directory can have contents. - `src` `<String>` Note that if `src` is a directory it will copy everything inside of this directory, not the entire directory itself (see [issue #537](https://github.com/jprichardson/node-fs-extra/issues/537)). - `dest` `<String>` Note that if `src` is a file, `dest` cannot be a directory (see [issue #323](https://github.com/jprichardson/node-fs-extra/issues/323)). @@ -11,6 +11,7 @@ Copy a file or directory. The directory can have contents. Like `cp -r`. - `preserveTimestamps` `<boolean>`: When true, will set last modification and access times to the ones of the original source files. When false, timestamp behavior is OS-dependent. Default is `false`. - `filter` `<Function>`: Function to filter copied files. Return `true` to include, `false` to exclude. Can also return a `Promise` that resolves to `true` or `false` (or pass in an `async` function). - `callback` `<Function>` + - `err` `<Error>` ## Example: @@ -20,13 +21,11 @@ const fs = require('fs-extra') // With a callback: fs.copy('/tmp/myfile', '/tmp/mynewfile', err => { if (err) return console.error(err) - console.log('success!') }) // copies file fs.copy('/tmp/mydir', '/tmp/mynewdir', err => { if (err) return console.error(err) - console.log('success!') }) // copies directory, even if it has subdirectories or files @@ -64,7 +63,6 @@ const filterFunc = (src, dest) => { fs.copy('/tmp/mydir', '/tmp/mynewdir', { filter: filterFunc }, err => { if (err) return console.error(err) - console.log('success!') }) ``` diff --git a/docs/emptyDir.md b/docs/emptyDir.md index 8f26dc10..15677608 100644 --- a/docs/emptyDir.md +++ b/docs/emptyDir.md @@ -6,6 +6,7 @@ Ensures that a directory is empty. Deletes directory contents if the directory i - `dir` `<String>` - `callback` `<Function>` + - `err` `<Error>` ## Example: @@ -16,7 +17,6 @@ const fs = require('fs-extra') // With a callback: fs.emptyDir('/tmp/some/dir', err => { if (err) return console.error(err) - console.log('success!') }) diff --git a/docs/ensureDir-sync.md b/docs/ensureDir-sync.md index f0f1cdb9..e6a9c893 100644 --- a/docs/ensureDir-sync.md +++ b/docs/ensureDir-sync.md @@ -1,11 +1,14 @@ # ensureDirSync(dir[,options]) -Ensures that the directory exists. If the directory structure does not exist, it is created. Like `mkdir -p`. If provided, options may specify the desired mode for the directory. +Ensures that the directory exists. If the directory structure does not exist, it is created. If provided, options may specify the desired mode for the directory. **Aliases:** `mkdirsSync()`, `mkdirpSync()` - `dir` `<String>` - `options` `<Integer>|<Object>` + - If it is `Integer`, it will be `mode`. + - If it is `Object`, it will be `{ mode: <Integer> }`. + ## Example: ```js diff --git a/docs/ensureDir.md b/docs/ensureDir.md index 85e9392d..521afee2 100644 --- a/docs/ensureDir.md +++ b/docs/ensureDir.md @@ -1,12 +1,15 @@ # ensureDir(dir[,options][,callback]) -Ensures that the directory exists. If the directory structure does not exist, it is created. Like `mkdir -p`. +Ensures that the directory exists. If the directory structure does not exist, it is created. **Aliases:** `mkdirs()`, `mkdirp()` - `dir` `<String>` - `options` `<Integer>|<Object>` + - If it is `Integer`, it will be `mode`. + - If it is `Object`, it will be `{ mode: <Integer> }`. - `callback` `<Function>` + - `err` `<Error>` ## Example: diff --git a/docs/ensureFile.md b/docs/ensureFile.md index a560e966..7e96e0c8 100644 --- a/docs/ensureFile.md +++ b/docs/ensureFile.md @@ -6,6 +6,7 @@ Ensures that the file exists. If the file that is requested to be created is in - `file` `<String>` - `callback` `<Function>` + - `err` `<Error>` ## Example: diff --git a/docs/ensureLink-sync.md b/docs/ensureLink-sync.md index 2a8b91ae..2196e640 100644 --- a/docs/ensureLink-sync.md +++ b/docs/ensureLink-sync.md @@ -1,19 +1,19 @@ -# ensureLinkSync(srcpath, dstpath) +# ensureLinkSync(srcPath, destPath) Ensures that the link exists. If the directory structure does not exist, it is created. **Alias:** `createLinkSync()` -- `srcpath` `<String>` -- `dstpath` `<String>` +- `srcPath` `<String>` +- `destPath` `<String>` ## Example: ```js const fs = require('fs-extra') -const srcpath = '/tmp/file.txt' -const dstpath = '/tmp/this/path/does/not/exist/file.txt' -fs.ensureLinkSync(srcpath, dstpath) +const srcPath = '/tmp/file.txt' +const destPath = '/tmp/this/path/does/not/exist/file.txt' +fs.ensureLinkSync(srcPath, destPath) // link has now been created, including the directory it is to be placed in ``` diff --git a/docs/ensureLink.md b/docs/ensureLink.md index acec6a9d..1214b5f6 100644 --- a/docs/ensureLink.md +++ b/docs/ensureLink.md @@ -1,29 +1,30 @@ -# ensureLink(srcpath, dstpath[, callback]) +# ensureLink(srcPath, destPath[, callback]) Ensures that the link exists. If the directory structure does not exist, it is created. **Alias:** `createLink()` -- `srcpath` `<String>` -- `dstpath` `<String>` +- `srcPath` `<String>` +- `destPath` `<String>` - `callback` `<Function>` + - `err` `<Error>` ## Example: ```js const fs = require('fs-extra') -const srcpath = '/tmp/file.txt' -const dstpath = '/tmp/this/path/does/not/exist/file.txt' +const srcPath = '/tmp/file.txt' +const destPath = '/tmp/this/path/does/not/exist/file.txt' // With a callback: -fs.ensureLink(srcpath, dstpath, err => { +fs.ensureLink(srcPath, destPath, err => { console.log(err) // => null // link has now been created, including the directory it is to be placed in }) // With Promises: -fs.ensureLink(srcpath, dstpath) +fs.ensureLink(srcPath, destPath) .then(() => { console.log('success!') }) @@ -41,5 +42,5 @@ async function example (src, dest) { } } -example(srcpath, dstpath) +example(srcPath, destPath) ``` diff --git a/docs/ensureSymlink-sync.md b/docs/ensureSymlink-sync.md index b3203831..febbe4f5 100644 --- a/docs/ensureSymlink-sync.md +++ b/docs/ensureSymlink-sync.md @@ -1,20 +1,20 @@ -# ensureSymlinkSync(srcpath, dstpath[, type]) +# ensureSymlinkSync(srcPath, destPath[, type]) Ensures that the symlink exists. If the directory structure does not exist, it is created. **Alias:** `createSymlinkSync()` -- `srcpath` `<String>` -- `dstpath` `<String>` -- `type` `<String>` +- `srcPath` `<String>` +- `destPath` `<String>` +- `type` `<String>` It is only available on Windows and ignored on other platforms. It can be set to `dir`, `file`, or `junction`. ## Example: ```js const fs = require('fs-extra') -const srcpath = '/tmp/file.txt' -const dstpath = '/tmp/this/path/does/not/exist/file.txt' -fs.ensureSymlinkSync(srcpath, dstpath) +const srcPath = '/tmp/file.txt' +const destPath = '/tmp/this/path/does/not/exist/file.txt' +fs.ensureSymlinkSync(srcPath, destPath) // symlink has now been created, including the directory it is to be placed in ``` diff --git a/docs/ensureSymlink.md b/docs/ensureSymlink.md index e8146cfa..737da480 100644 --- a/docs/ensureSymlink.md +++ b/docs/ensureSymlink.md @@ -1,30 +1,31 @@ -# ensureSymlink(srcpath, dstpath[, type][, callback]) +# ensureSymlink(srcPath, destPath[, type][, callback]) Ensures that the symlink exists. If the directory structure does not exist, it is created. **Alias:** `createSymlink()` -- `srcpath` `<String>` -- `dstpath` `<String>` -- `type` `<String>` +- `srcPath` `<String>` +- `destPath` `<String>` +- `type` `<String>` It is only available on Windows and ignored on other platforms. It can be set to `dir`, `file`, or `junction`. - `callback` `<Function>` + - `err` `<Error>` ## Example: ```js const fs = require('fs-extra') -const srcpath = '/tmp/file.txt' -const dstpath = '/tmp/this/path/does/not/exist/file.txt' +const srcPath = '/tmp/file.txt' +const destPath = '/tmp/this/path/does/not/exist/file.txt' // With a callback: -fs.ensureSymlink(srcpath, dstpath, err => { +fs.ensureSymlink(srcPath, destPath, err => { console.log(err) // => null // symlink has now been created, including the directory it is to be placed in }) // With Promises: -fs.ensureSymlink(srcpath, dstpath) +fs.ensureSymlink(srcPath, destPath) .then(() => { console.log('success!') }) @@ -42,5 +43,5 @@ async function example (src, dest) { } } -example(srcpath, dstpath) +example(srcPath, destPath) ``` diff --git a/docs/move-sync.md b/docs/move-sync.md index d5153b58..53fde492 100644 --- a/docs/move-sync.md +++ b/docs/move-sync.md @@ -20,5 +20,5 @@ fs.moveSync('/tmp/somefile', '/tmp/does/not/exist/yet/somefile') ```js const fs = require('fs-extra') -fs.moveSync('/tmp/somedir', '/tmp/may/already/existed/somedir', { overwrite: true }) +fs.moveSync('/tmp/somedir', '/tmp/may/already/exist/somedir', { overwrite: true }) ``` diff --git a/docs/move.md b/docs/move.md index 5f70853e..586d46ca 100644 --- a/docs/move.md +++ b/docs/move.md @@ -7,24 +7,24 @@ Moves a file or directory, even across devices. - `options` `<Object>` - `overwrite` `<boolean>`: overwrite existing file or directory, default is `false`. - `callback` `<Function>` + - `err` `<Error>` ## Example: ```js const fs = require('fs-extra') -const srcpath = '/tmp/file.txt' -const dstpath = '/tmp/this/path/does/not/exist/file.txt' +const src = '/tmp/file.txt' +const dest = '/tmp/this/path/does/not/exist/file.txt' // With a callback: -fs.move(srcpath, dstpath, err => { +fs.move(src, dest, err => { if (err) return console.error(err) - console.log('success!') }) // With Promises: -fs.move(srcpath, dstpath) +fs.move(src, dest) .then(() => { console.log('success!') }) @@ -35,14 +35,14 @@ fs.move(srcpath, dstpath) // With async/await: async function example (src, dest) { try { - await fs.move(srcpath, dstpath) + await fs.move(src, dest) console.log('success!') } catch (err) { console.error(err) } } -example(srcpath, dstpath) +example(src, dest) ``` **Using `overwrite` option** @@ -50,9 +50,8 @@ example(srcpath, dstpath) ```js const fs = require('fs-extra') -fs.move('/tmp/somedir', '/tmp/may/already/existed/somedir', { overwrite: true }, err => { +fs.move('/tmp/somedir', '/tmp/may/already/exist/somedir', { overwrite: true }, err => { if (err) return console.error(err) - console.log('success!') }) ``` diff --git a/docs/outputFile-sync.md b/docs/outputFile-sync.md index fc7abdf9..4d5bef8e 100644 --- a/docs/outputFile-sync.md +++ b/docs/outputFile-sync.md @@ -1,10 +1,10 @@ # outputFileSync(file, data[, options]) -Almost the same as `writeFileSync` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `file` must be a file path (a buffer or a file descriptor is not allowed). `options` are what you'd pass to [`fs.writeFileSync()`](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options). +Almost the same as `writeFileSync` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `file` must be a file path (a buffer or a file descriptor is not allowed). - `file` `<String>` - `data` `<String> | <Buffer> | <Uint8Array>` -- `options` `<Object> | <String>` +- `options` `<Object> | <String>` (the same as [`fs.writeFileSync()` options](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options)) ## Example: diff --git a/docs/outputFile.md b/docs/outputFile.md index ed9c19d6..b0449e4c 100644 --- a/docs/outputFile.md +++ b/docs/outputFile.md @@ -1,11 +1,12 @@ # outputFile(file, data[, options][, callback]) -Almost the same as `writeFile` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `file` must be a file path (a buffer or a file descriptor is not allowed). `options` are what you'd pass to [`fs.writeFile()`](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback). +Almost the same as `writeFile` (i.e. it [overwrites](http://pages.citebite.com/v2o5n8l2f5reb)), except that if the parent directory does not exist, it's created. `file` must be a file path (a buffer or a file descriptor is not allowed). - `file` `<String>` - `data` `<String> | <Buffer> | <Uint8Array>` -- `options` `<Object> | <String>` +- `options` `<Object> | <String>` (the same as [`fs.writeFile()` options](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback)) - `callback` `<Function>` + - `err` `<Error>` ## Example: diff --git a/docs/outputJson-sync.md b/docs/outputJson-sync.md index c42497cf..3e80ddef 100644 --- a/docs/outputJson-sync.md +++ b/docs/outputJson-sync.md @@ -10,7 +10,7 @@ Almost the same as [`writeJsonSync`](writeJson-sync.md), except that if the dire - `spaces` `<Number|String>` Number of spaces to indent; or a string to use for indentation (i.e. pass `'\t'` for tab indentation). See [the docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_space_argument) for more info. - `EOL` `<String>` Set EOL character. Default is `\n`. - `replacer` [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter) - - Also accepts [`fs.writeFileSync` options](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options) + - Also accepts [`fs.writeFileSync()` options](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options) ## Example: diff --git a/docs/outputJson.md b/docs/outputJson.md index d5a6d7c7..cef4c6fa 100644 --- a/docs/outputJson.md +++ b/docs/outputJson.md @@ -10,8 +10,9 @@ Almost the same as [`writeJson`](writeJson.md), except that if the directory doe - `spaces` `<Number|String>` Number of spaces to indent; or a string to use for indentation (i.e. pass `'\t'` for tab indentation). See [the docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_space_argument) for more info. - `EOL` `<String>` Set EOL character. Default is `\n`. - `replacer` [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter) - - Also accepts [`fs.writeFile` options](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback) + - Also accepts [`fs.writeFile()` options](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback) - `callback` `<Function>` + - `err` `<Error>` ## Example: diff --git a/docs/pathExists.md b/docs/pathExists.md index 7a317d9f..b31ed77c 100644 --- a/docs/pathExists.md +++ b/docs/pathExists.md @@ -4,6 +4,8 @@ Test whether or not the given path exists by checking with the file system. Like - `file` `<String>` - `callback` `<Function>` + - `err` `<Error>` + - `exists` `<boolean>` ## Example: diff --git a/docs/readJson-sync.md b/docs/readJson-sync.md index 1fc6519d..712c9985 100644 --- a/docs/readJson-sync.md +++ b/docs/readJson-sync.md @@ -1,12 +1,11 @@ # readJsonSync(file[, options]) -Reads a JSON file and then parses it into an object. `options` are the same -that you'd pass to [`jsonFile.readFileSync`](https://github.com/jprichardson/node-jsonfile#readfilesyncfilename-options). +Reads a JSON file and then parses it into an object. **Alias:** `readJSONSync()` - `file` `<String>` -- `options` `<Object>` +- `options` `<Object>` (the same as [`jsonFile.readFileSync()` options](https://github.com/jprichardson/node-jsonfile#readfilesyncfilename-options)) ## Example: diff --git a/docs/readJson.md b/docs/readJson.md index 881e7972..e7500a2b 100644 --- a/docs/readJson.md +++ b/docs/readJson.md @@ -1,13 +1,14 @@ # readJson(file[, options][, callback]) -Reads a JSON file and then parses it into an object. `options` are the same -that you'd pass to [`jsonFile.readFile`](https://github.com/jprichardson/node-jsonfile#readfilefilename-options-callback). +Reads a JSON file and then parses it into an object. **Alias:** `readJSON()` - `file` `<String>` -- `options` `<Object>` +- `options` `<Object>` (the same as [`jsonFile.readFile()` options](https://github.com/jprichardson/node-jsonfile#readfilefilename-options-callback)) - `callback` `<Function>` + - `err` `<Error>` + - `obj` `<Object>` ## Example: @@ -17,7 +18,6 @@ const fs = require('fs-extra') // With a callback: fs.readJson('./package.json', (err, packageObj) => { if (err) console.error(err) - console.log(packageObj.version) // => 0.1.3 }) @@ -34,7 +34,6 @@ fs.readJson('./package.json') async function example () { try { const packageObj = await fs.readJson('./package.json') - console.log(packageObj.version) // => 0.1.3 } catch (err) { console.error(err) @@ -58,7 +57,6 @@ fs.writeFileSync(file, data) // With a callback: fs.readJson(file, { throws: false }, (err, obj) => { if (err) console.error(err) - console.log(obj) // => null }) @@ -74,7 +72,6 @@ fs.readJson(file, { throws: false }) // With async/await: async function example (f) { const obj = await fs.readJson(f, { throws: false }) - console.log(obj) // => null } diff --git a/docs/remove-sync.md b/docs/remove-sync.md index 56fa9ada..3f763b03 100644 --- a/docs/remove-sync.md +++ b/docs/remove-sync.md @@ -1,6 +1,6 @@ # removeSync(path) -Removes a file or directory. The directory can have contents. If the path does not exist, silently does nothing. Like `rm -rf`. +Removes a file or directory. The directory can have contents. If the path does not exist, silently does nothing. - `path` `<String>` diff --git a/docs/remove.md b/docs/remove.md index be319fa3..56dd2cfe 100644 --- a/docs/remove.md +++ b/docs/remove.md @@ -1,9 +1,10 @@ # remove(path[, callback]) -Removes a file or directory. The directory can have contents. If the path does not exist, silently does nothing. Like `rm -rf`. +Removes a file or directory. The directory can have contents. If the path does not exist, silently does nothing. - `path` `<String>` - `callback` `<Function>` + - `err` `<Error>` ## Example: @@ -14,13 +15,11 @@ const fs = require('fs-extra') // With a callback: fs.remove('/tmp/myfile', err => { if (err) return console.error(err) - console.log('success!') }) fs.remove('/home/jprichardson', err => { if (err) return console.error(err) - console.log('success!') // I just deleted my entire HOME directory. }) diff --git a/docs/writeJson-sync.md b/docs/writeJson-sync.md index b98e0c7d..913440a3 100644 --- a/docs/writeJson-sync.md +++ b/docs/writeJson-sync.md @@ -10,7 +10,7 @@ Writes an object to a JSON file. - `spaces` `<Number|String>` Number of spaces to indent; or a string to use for indentation (i.e. pass `'\t'` for tab indentation). See [the docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_space_argument) for more info. - `EOL` `<String>` Set EOL character. Default is `\n`. - `replacer` [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter) - - Also accepts [`fs.writeFileSync` options](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options) + - Also accepts [`fs.writeFileSync()` options](https://nodejs.org/api/fs.html#fs_fs_writefilesync_file_data_options) ## Example: diff --git a/docs/writeJson.md b/docs/writeJson.md index 216d1348..70dbf2bf 100644 --- a/docs/writeJson.md +++ b/docs/writeJson.md @@ -10,8 +10,9 @@ Writes an object to a JSON file. - `spaces` `<Number|String>` Number of spaces to indent; or a string to use for indentation (i.e. pass `'\t'` for tab indentation). See [the docs](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_space_argument) for more info. - `EOL` `<String>` Set EOL character. Default is `\n`. - `replacer` [JSON replacer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify#The_replacer_parameter) - - Also accepts [`fs.writeFile` options](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback) + - Also accepts [`fs.writeFile()` options](https://nodejs.org/api/fs.html#fs_fs_writefile_file_data_options_callback) - `callback` `<Function>` + - `err` `<Error>` ## Example: @@ -21,7 +22,6 @@ const fs = require('fs-extra') // With a callback: fs.writeJson('./package.json', {name: 'fs-extra'}, err => { if (err) return console.error(err) - console.log('success!') }) diff --git a/package.json b/package.json index 1f251f18..d5b5dc1e 100644 --- a/package.json +++ b/package.json @@ -1,7 +1,7 @@ { "name": "fs-extra", "version": "9.0.0", - "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.", + "description": "fs-extra contains methods that aren't included in the vanilla Node.js fs package. Such as recursive mkdir, copy, and remove.", "engines": { "node": ">=10" },