| 1 | # copy-concurrently
|
| 2 |
|
| 3 | Copy files, directories and symlinks
|
| 4 |
|
| 5 | ```
|
| 6 | const copy = require('copy-concurrently')
|
| 7 | copy('/path/to/thing', '/new/path/thing').then(() => {
|
| 8 | // this is now copied
|
| 9 | }).catch(err => {
|
| 10 | // oh noooo
|
| 11 | })
|
| 12 | ```
|
| 13 |
|
| 14 | Copies files, directories and symlinks. Ownership is maintained when
|
| 15 | running as root, permissions are always maintained. On Windows, if symlinks
|
| 16 | are unavailable then junctions will be used.
|
| 17 |
|
| 18 | ## PUBLIC INTERFACE
|
| 19 |
|
| 20 | ### copy(from, to, [options]) → Promise
|
| 21 |
|
| 22 | Recursively copies `from` to `to` and resolves its promise when finished.
|
| 23 | If `to` already exists then the promise will be rejected with an `EEXIST`
|
| 24 | error.
|
| 25 |
|
| 26 | Options are:
|
| 27 |
|
| 28 | * maxConcurrency – (Default: `1`) The maximum number of concurrent copies to do at once.
|
| 29 | * recurseWith - (Default: `copy.item`) The function to call on each file after recursing into a directory.
|
| 30 | * isWindows - (Default: `process.platform === 'win32'`) If true enables Windows symlink semantics. This requires
|
| 31 | an extra `stat` to determine if the destination of a symlink is a file or directory. If symlinking a directory
|
| 32 | fails then we'll try making a junction instead.
|
| 33 |
|
| 34 | Options can also include dependency injection:
|
| 35 |
|
| 36 | * Promise - (Default: `global.Promise`) The promise implementation to use, defaults to Node's.
|
| 37 | * fs - (Default: `require('fs')`) The filesystem module to use. Can be used
|
| 38 | to use `graceful-fs` or to inject a mock.
|
| 39 | * writeStreamAtomic - (Default: `require('fs-write-stream-atomic')`) The
|
| 40 | implementation of `writeStreamAtomic` to use. Used to inject a mock.
|
| 41 | * getuid - (Default: `process.getuid`) A function that returns the current UID. Used to inject a mock.
|
| 42 |
|
| 43 | ## EXTENSION INTERFACE
|
| 44 |
|
| 45 | Ordinarily you'd only call `copy` above. But it's possible to use it's
|
| 46 | component functions directly. This is useful if, say, you're writing
|
| 47 | [move-concurently](https://npmjs.com/package/move-concurrently).
|
| 48 |
|
| 49 | ### copy.file(from, to, options) → Promise
|
| 50 |
|
| 51 | Copies an ordinary file `from` to destination `to`. Uses
|
| 52 | `fs-write-stream-atomic` to ensure that the file is either entirely copied
|
| 53 | or not at all.
|
| 54 |
|
| 55 | Options are:
|
| 56 |
|
| 57 | * uid, gid - (Optional) If `getuid()` is `0` then this and gid will be used to
|
| 58 | set the user and group of `to`. If uid is present then gid must be too.
|
| 59 | * mode - (Optional) If set then `to` will have its perms set to `mode`.
|
| 60 | * fs - (Default: `require('fs')`) The filesystem module to use. Can be used
|
| 61 | to use `graceful-fs` or to inject a mock.
|
| 62 | * Promise - (Default: `global.Promise`) The promise implementation to use, defaults to Node's.
|
| 63 | * writeStreamAtomic - (Default `require('fs-write-stream-atomic')`) The
|
| 64 | implementation of `writeStreamAtomic` to use. Used to inject a mock.
|
| 65 |
|
| 66 | ### copy.symlink(from, to, options) → Promise
|
| 67 |
|
| 68 | Copies a symlink `from` to destination `to`. If you're using Windows and
|
| 69 | symlinking fails and what you're linking is a directory then junctions will
|
| 70 | be tried instead.
|
| 71 |
|
| 72 | Options are:
|
| 73 |
|
| 74 | * top - The top level the copy is being run from. This is used to determine
|
| 75 | if the symlink destination is within the set of files we're copying or
|
| 76 | outside it.
|
| 77 | * fs - (Default: `require('fs')`) The filesystem module to use. Can be used
|
| 78 | to use `graceful-fs` or to inject a mock.
|
| 79 | * Promise - (Default: `global.Promise`) The promise implementation to use, defaults to Node's.
|
| 80 | * isWindows - (Default: `process.platform === 'win32'`) If true enables Windows symlink semantics. This requires
|
| 81 | an extra `stat` to determine if the destination of a symlink is a file or directory. If symlinking a directory
|
| 82 | fails then we'll try making a junction instead.
|
| 83 |
|
| 84 | ### copy.recurse(from, to, options) → Promise
|
| 85 |
|
| 86 | Reads all of the files in directory `from` and adds them to the `queue`
|
| 87 | using `recurseWith` (by default `copy.item`).
|
| 88 |
|
| 89 | Options are:
|
| 90 |
|
| 91 | * queue - A [`run-queue`](https://npmjs.com/package/run-queue) object to add files found inside `from` to.
|
| 92 | * recurseWith - (Default: `copy.item`) The function to call on each file after recursing into a directory.
|
| 93 | * uid, gid - (Optional) If `getuid()` is `0` then this and gid will be used to
|
| 94 | set the user and group of `to`. If uid is present then gid must be too.
|
| 95 | * mode - (Optional) If set then `to` will have its perms set to `mode`.
|
| 96 | * fs - (Default: `require('fs')`) The filesystem module to use. Can be used
|
| 97 | to use `graceful-fs` or to inject a mock.
|
| 98 | * getuid - (Default: `process.getuid`) A function that returns the current UID. Used to inject a mock.
|
| 99 |
|
| 100 | ### copy.item(from, to, options) → Promise
|
| 101 |
|
| 102 | Copies some kind of `from` to destination `to`. This looks at the filetype
|
| 103 | and calls `copy.file`, `copy.symlink` or `copy.recurse` as appropriate.
|
| 104 |
|
| 105 | Symlink copies are queued with a priority such that they happen after all
|
| 106 | file and directory copies as you can't create a junction on windows to a
|
| 107 | file that doesn't exist yet.
|
| 108 |
|
| 109 | Options are:
|
| 110 |
|
| 111 | * top - The top level the copy is being run from. This is used to determine
|
| 112 | if the symlink destination is within the set of files we're copying or
|
| 113 | outside it.
|
| 114 | * queue - The [`run-queue`](https://npmjs.com/package/run-queue) object to
|
| 115 | pass to `copy.recurse` if `from` is a directory.
|
| 116 | * recurseWith - (Default: `copy.item`) The function to call on each file after recursing into a directory.
|
| 117 | * uid, gid - (Optional) If `getuid()` is `0` then this and gid will be used to
|
| 118 | set the user and group of `to`. If uid is present then gid must be too.
|
| 119 | * mode - (Optional) If set then `to` will have its perms set to `mode`.
|
| 120 | * fs - (Default: `require('fs')`) The filesystem module to use. Can be used
|
| 121 | to use `graceful-fs` or to inject a mock.
|
| 122 | * getuid - (Default: `process.getuid`) A function that returns the current UID. Used to inject a mock.
|
| 123 | * isWindows - (Default: `process.platform === 'win32'`) If true enables Windows symlink semantics. This requires
|
| 124 | an extra `stat` to determine if the destination of a symlink is a file or directory. If symlinking a directory
|
| 125 | fails then we'll try making a junction instead.
|
| 126 | * Promise - (Default: `global.Promise`) The promise implementation to use, defaults to Node's.
|
| 127 | * writeStreamAtomic - (Default `require('fs-write-stream-atomic')`) The
|
| 128 | implementation of `writeStreamAtomic` to use. Used to inject a mock.
|