diff options
author | bcoe <bencoe@google.com> | 2021-08-08 23:48:01 +0300 |
---|---|---|
committer | Benjamin Coe <bencoe@google.com> | 2021-08-12 05:53:32 +0300 |
commit | 87d6fd7e696ee02178a8dc33a51e8e59bdc61d68 (patch) | |
tree | e9c76b5f1d9f4ba4f51528b2ef8e41b82b6e2f4f /doc/api | |
parent | 4ece669c6205ec78abfdadfe78869bbb8411463e (diff) |
fs: add recursive cp method
Introduces recursive cp method, based on fs-extra implementation.
PR-URL: https://github.com/nodejs/node/pull/39372
Fixes: https://github.com/nodejs/node/issues/35880
Refs: https://github.com/nodejs/tooling/issues/98
Reviewed-By: Matteo Collina <matteo.collina@gmail.com>
Reviewed-By: Michaƫl Zasso <targos@protonmail.com>
Reviewed-By: Antoine du Hamel <duhamelantoine1995@gmail.com>
Reviewed-By: James M Snell <jasnell@gmail.com>
Reviewed-By: Ian Sutherland <ian@iansutherland.ca>
Diffstat (limited to 'doc/api')
-rw-r--r-- | doc/api/errors.md | 69 | ||||
-rw-r--r-- | doc/api/fs.md | 91 |
2 files changed, 160 insertions, 0 deletions
diff --git a/doc/api/errors.md b/doc/api/errors.md index 9b1a556d2b0..67dc1781d0b 100644 --- a/doc/api/errors.md +++ b/doc/api/errors.md @@ -1115,6 +1115,74 @@ added: v14.0.0 Used when a feature that is not available to the current platform which is running Node.js is used. +<a id="ERR_FS_CP_DIR_TO_NON_DIR"></a> +### `ERR_FS_CP_DIR_TO_NON_DIR` +<!-- +added: REPLACEME +--> + +An attempt was made to copy a directory to a non-directory (file, symlink, +etc.) using [`fs.cp()`][]. + +<a id="ERR_FS_CP_EEXIST"></a> +### `ERR_FS_CP_EEXIST` +<!-- +added: REPLACEME +--> + +An attempt was made to copy over a file that already existed with +[`fs.cp()`][], with the `force` and `errorOnExist` set to `true`. + +<a id="ERR_FS_CP_EINVAL"></a> +### `ERR_FS_CP_EINVAL` +<!-- +added: REPLACEME +--> + +When using [`fs.cp()`][], `src` or `dest` pointed to an invalid path. + +<a id="ERR_FS_CP_FIFO_PIPE"></a> +### `ERR_FS_CP_FIFO_PIPE` +<!-- +added: REPLACEME +--> + +An attempt was made to copy a named pipe with [`fs.cp()`][]. + +<a id="ERR_FS_CP_NON_DIR_TO_DIR"></a> +### `ERR_FS_CP_NON_DIR_TO_DIR` +<!-- +added: REPLACEME +--> + +An attempt was made to copy a non-directory (file, symlink, etc.) to a directory +using [`fs.cp()`][]. + +<a id="ERR_FS_CP_SOCKET"></a> +### `ERR_FS_CP_SOCKET` +<!-- +added: REPLACEME +--> + +An attempt was made to copy to a socket with [`fs.cp()`][]. + +<a id="ERR_FS_CP_SYMLINK_TO_SUBDIRECTORY"></a> +### `ERR_FS_CP_SYMLINK_TO_SUBDIRECTORY` +<!-- +added: REPLACEME +--> + +When using [`fs.cp()`][], a symlink in `dest` pointed to a subdirectory +of `src`. + +<a id="ERR_FS_CP_UNKNOWN"></a> +### `ERR_FS_CP_UNKNOWN` +<!-- +added: REPLACEME +--> + +An attempt was made to copy to an unknown file type with [`fs.cp()`][]. + <a id="ERR_FS_EISDIR"></a> ### `ERR_FS_EISDIR` @@ -2822,6 +2890,7 @@ The native call from `process.cpuUsage` could not be processed. [`dgram.remoteAddress()`]: dgram.md#dgram_socket_remoteaddress [`errno`(3) man page]: https://man7.org/linux/man-pages/man3/errno.3.html [`fs.Dir`]: fs.md#fs_class_fs_dir +[`fs.cp()`]: fs.md#fs_fs_cp_src_dest_options_callback [`fs.readFileSync`]: fs.md#fs_fs_readfilesync_path_options [`fs.readdir`]: fs.md#fs_fs_readdir_path_options_callback [`fs.symlink()`]: fs.md#fs_fs_symlink_target_path_type_callback diff --git a/doc/api/fs.md b/doc/api/fs.md index f17f0559753..a98a937c411 100644 --- a/doc/api/fs.md +++ b/doc/api/fs.md @@ -739,6 +739,37 @@ try { } ``` +### `fsPromises.cp(src, dest[, options])` +<!-- YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +* `src` {string|URL} source path to copy. +* `dest` {string|URL} destination path to copy to. +* `options` {Object} + * `dereference` {boolean} dereference symlinks. **Default:** `false`. + * `errorOnExist` {boolean} when `force` is `false`, and the destination + exists, throw an error. **Default:** `false`. + * `filter` {Function} Function to filter copied files/directories. Return + `true` to copy the item, `false` to ignore it. Can also return a `Promise` + that resolves to `true` or `false` **Default:** `undefined`. + * `force` {boolean} overwrite existing file or directory. _The copy + operation will ignore errors if you set this to false and the destination + exists. Use the `errorOnExist` option to change this behavior. + **Default:** `true`. + * `preserveTimestamps` {boolean} When `true` timestamps from `src` will + be preserved. **Default:** `false`. + * `recursive` {boolean} copy directories recursively **Default:** `false` +* Returns: {Promise} Fulfills with `undefined` upon success. + +Asynchronously copies the entire directory structure from `src` to `dest`, +including subdirectories and files. + +When copying a directory to another directory, globs are not supported and +behavior is similar to `cp dir1/ dir2/`. + ### `fsPromises.lchmod(path, mode)` <!-- YAML deprecated: v10.0.0 @@ -1848,6 +1879,37 @@ copyFile('source.txt', 'destination.txt', callback); copyFile('source.txt', 'destination.txt', constants.COPYFILE_EXCL, callback); ``` +### `fs.cp(src, dest[, options], callback)` +<!-- YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +* `src` {string|URL} source path to copy. +* `dest` {string|URL} destination path to copy to. +* `options` {Object} + * `dereference` {boolean} dereference symlinks. **Default:** `false`. + * `errorOnExist` {boolean} when `force` is `false`, and the destination + exists, throw an error. **Default:** `false`. + * `filter` {Function} Function to filter copied files/directories. Return + `true` to copy the item, `false` to ignore it. Can also return a `Promise` + that resolves to `true` or `false` **Default:** `undefined`. + * `force` {boolean} overwrite existing file or directory. _The copy + operation will ignore errors if you set this to false and the destination + exists. Use the `errorOnExist` option to change this behavior. + **Default:** `true`. + * `preserveTimestamps` {boolean} When `true` timestamps from `src` will + be preserved. **Default:** `false`. + * `recursive` {boolean} copy directories recursively **Default:** `false` +* `callback` {Function} + +Asynchronously copies the entire directory structure from `src` to `dest`, +including subdirectories and files. + +When copying a directory to another directory, globs are not supported and +behavior is similar to `cp dir1/ dir2/`. + ### `fs.createReadStream(path[, options])` <!-- YAML added: v0.1.31 @@ -4321,6 +4383,35 @@ console.log('source.txt was copied to destination.txt'); copyFileSync('source.txt', 'destination.txt', constants.COPYFILE_EXCL); ``` +### `fs.cpSync(src, dest[, options])` +<!-- YAML +added: REPLACEME +--> + +> Stability: 1 - Experimental + +* `src` {string|URL} source path to copy. +* `dest` {string|URL} destination path to copy to. +* `options` {Object} + * `dereference` {boolean} dereference symlinks. **Default:** `false`. + * `errorOnExist` {boolean} when `force` is `false`, and the destination + exists, throw an error. **Default:** `false`. + * `filter` {Function} Function to filter copied files/directories. Return + `true` to copy the item, `false` to ignore it. **Default:** `undefined` + * `force` {boolean} overwrite existing file or directory. _The copy + operation will ignore errors if you set this to false and the destination + exists. Use the `errorOnExist` option to change this behavior. + **Default:** `true`. + * `preserveTimestamps` {boolean} When `true` timestamps from `src` will + be preserved. **Default:** `false`. + * `recursive` {boolean} copy directories recursively **Default:** `false` + +Synchronously copies the entire directory structure from `src` to `dest`, +including subdirectories and files. + +When copying a directory to another directory, globs are not supported and +behavior is similar to `cp dir1/ dir2/`. + ### `fs.existsSync(path)` <!-- YAML added: v0.1.21 |