64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
|
# ncp - Asynchronous recursive file & directory copying
|
||
|
|
|
||
|
|
[](http://travis-ci.org/AvianFlu/ncp)
|
||
|
|
|
||
|
|
Think `cp -r`, but pure node, and asynchronous. `ncp` can be used both as a CLI tool and programmatically.
|
||
|
|
|
||
|
|
## Command Line usage
|
||
|
|
|
||
|
|
Usage is simple: `ncp [source] [dest] [--limit=concurrency limit]
|
||
|
|
[--filter=filter] --stopOnErr`
|
||
|
|
|
||
|
|
The 'filter' is a Regular Expression - matched files will be copied.
|
||
|
|
|
||
|
|
The 'concurrency limit' is an integer that represents how many pending file system requests `ncp` has at a time.
|
||
|
|
|
||
|
|
'stoponerr' is a boolean flag that will tell `ncp` to stop immediately if any
|
||
|
|
errors arise, rather than attempting to continue while logging errors. The default behavior is to complete as many copies as possible, logging errors along the way.
|
||
|
|
|
||
|
|
If there are no errors, `ncp` will output `done.` when complete. If there are errors, the error messages will be logged to `stdout` and to `./ncp-debug.log`, and the copy operation will attempt to continue.
|
||
|
|
|
||
|
|
## Programmatic usage
|
||
|
|
|
||
|
|
Programmatic usage of `ncp` is just as simple. The only argument to the completion callback is a possible error.
|
||
|
|
|
||
|
|
```javascript
|
||
|
|
var ncp = require('ncp').ncp;
|
||
|
|
|
||
|
|
ncp.limit = 16;
|
||
|
|
|
||
|
|
ncp(source, destination, function (err) {
|
||
|
|
if (err) {
|
||
|
|
return console.error(err);
|
||
|
|
}
|
||
|
|
console.log('done!');
|
||
|
|
});
|
||
|
|
```
|
||
|
|
|
||
|
|
You can also call ncp like `ncp(source, destination, options, callback)`.
|
||
|
|
`options` should be a dictionary. Currently, such options are available:
|
||
|
|
|
||
|
|
* `options.filter` - a `RegExp` instance, against which each file name is
|
||
|
|
tested to determine whether to copy it or not, or a function taking single
|
||
|
|
parameter: copied file name, returning `true` or `false`, determining
|
||
|
|
whether to copy file or not.
|
||
|
|
|
||
|
|
* `options.transform` - a function: `function (read, write) { read.pipe(write) }`
|
||
|
|
used to apply streaming transforms while copying.
|
||
|
|
|
||
|
|
* `options.clobber` - boolean=true. if set to false, `ncp` will not overwrite
|
||
|
|
destination files that already exist.
|
||
|
|
|
||
|
|
* `options.dereference` - boolean=false. If set to true, `ncp` will follow symbolic
|
||
|
|
links. For example, a symlink in the source tree pointing to a regular file
|
||
|
|
will become a regular file in the destination tree. Broken symlinks will result in
|
||
|
|
errors.
|
||
|
|
|
||
|
|
* `options.stopOnErr` - boolean=false. If set to true, `ncp` will behave like `cp -r`,
|
||
|
|
and stop on the first error it encounters. By default, `ncp` continues copying, logging all
|
||
|
|
errors and returning an array.
|
||
|
|
|
||
|
|
* `options.errs` - stream. If `options.stopOnErr` is `false`, a stream can be provided, and errors will be written to this stream.
|
||
|
|
|
||
|
|
Please open an issue if any bugs arise. As always, I accept (working) pull requests, and refunds are available at `/dev/null`.
|