cpy

> Copy files

Why

- Fast by using streams.
- Resilient by using graceful-fs.
- User-friendly by accepting globs and creating non-existent destination directories.
- User-friendly error messages.
- Progress reporting.

Install

``
$ npm install cpy
`

Usage

`js
import cpy from 'cpy';

await cpy([
'source/*.png', // Copy all .png files
'!source/goat.png', // Ignore goat.png
], 'destination');

// Copy node_modules to destination/node_modules
await cpy('node_modules', 'destination');

// Copy node_modules content to destination
await cpy('node_modules/**', 'destination');

// Copy node_modules structure but skip all files except package.json files
await cpy('node_modules/*/.json', 'destination');

// Copy all png files into destination without keeping directory structure
await cpy('*/.png', 'destination', {flat: true});

console.log('Files copied!');
`

API

$3

Returns a Promise with the destination file paths.

#### source

Type: string | string[]

Files to copy.

If any of the files do not exist, an error will be thrown (does not apply to globs).

#### destination

Type: string

Destination directory.

#### options

Type: object

Options are passed to globby.

In addition, you can specify the below options.

##### cwd

Type: string\
Default: process.cwd()

Working directory to find source files.

##### overwrite

Type: boolean\
Default: true

Overwrite existing files.

##### flat

Type: boolean\
Default: false

Flatten directory structure. All copied files will be put in the same directory.

`js
import cpy from 'cpy';

await cpy('src/*/.js', 'destination', {
flat: true
});
`

##### rename

Type: string | Function

Filename or function returning a filename used to rename every file in source.

`js
import cpy from 'cpy';

await cpy('foo.js', 'destination', {
rename: basename => prefix-${basename}
});

await cpy('foo.js', 'destination', {
rename: 'new-name'
});
`

##### concurrency

Type: number\
Default: (os.cpus().length || 1) * 2

Number of files being copied concurrently.

##### ignoreJunk

Type: boolean\
Default: true

Ignores junk files.

##### filter

Type: Function

Function to filter files to copy.

Receives a source file object as the first argument.

Return true to include, false to exclude. You can also return a Promise that resolves to true or false.

`js
import cpy from 'cpy';

await cpy('foo', 'destination', {
filter: file => file.extension !== 'nocopy'
});
`

##### Source file object

###### path

Type: string\
Example: '/tmp/dir/foo.js'

Resolved path to the file.

###### relativePath

Type: string\
Example: 'dir/foo.js' if cwd was '/tmp'

Relative path to the file from cwd.

###### name

Type: string\
Example: 'foo.js'

Filename with extension.

###### nameWithoutExtension

Type: string\
Example: 'foo'

Filename without extension.

###### extension

Type: string\
Example: 'js'

File extension.

Progress reporting

$3

#### handler(progress)

Type: Function

##### progress

`js
{
completedFiles: number,
totalFiles: number,
completedSize: number,
percent: number
}
`

- completedSize is in bytes
- percent is a value between 0 and 1

Note that the .on() method is available only right after the initial cpy call, so make sure you add a handler before awaiting the promise:

`js
import cpy from 'cpy';

await cpy(source, destination).on('progress', progress => {
// …
});
``

Related

- cpy-cli - CLI for this module
- cp-file - Copy a single file
- move-file - Move a file
- make-dir - Make a directory and its parents if needed