# cpy

> Copy files

## Why

- Fast by [cloning](https://stackoverflow.com/questions/71629903/node-js-why-we-should-use-copyfile-ficlone-and-copyfile-ficlone-force-what-is) the files whenever possible.
- Resilient by using [graceful-fs](https://github.com/isaacs/node-graceful-fs).
- User-friendly by accepting [globs](https://github.com/sindresorhus/globby#globbing-patterns) and creating non-existent destination directories.
- User-friendly error messages.
- Progress reporting.

## Install

```sh
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 .json files
await cpy('node_modules/**/*.json', 'destination');

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

// Progress reporting
await cpy('source/**', 'destination', {
	onProgress: progress => {
		console.log(`Progress: ${Math.round(progress.percent * 100)}%`);
	}
});

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

## API

### cpy(source, destination, options?)

Returns a `Promise<string[]>` 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).

When multiple source files resolve to the same destination path, for example with overlapping globs, `flat`, or `rename`, the destination is written once and the last source wins. The `ignoreExisting` option keeps the first source instead, and `update` keeps the newest unless `overwrite` is `false`, which disables `update`.

#### destination

Type: `string`

Destination directory.

#### options

Type: `object`

Options are passed to [globby](https://github.com/sindresorhus/globby#options).

Note: Dotfiles are excluded by default. Set `dot: true` to include them.

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.

##### ignoreExisting

Type: `boolean`\
Default: `false`

Skip files when the destination path already exists.

This option takes precedence over `overwrite`.

##### update

Type: `boolean`\
Default: `false`

Only overwrite when the source is newer, or when sizes differ with the same modification time. Ignored when `overwrite` is `false` or `ignoreExisting` is `true`.

##### 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
});
```

##### base

Type: `'cwd' | 'pattern'`\
Default: `undefined`

Choose how destination paths are calculated for patterns. By default, globs are resolved relative to their parent and explicit paths are resolved relative to `cwd`. Set to `'pattern'` to make explicit paths behave like globs, or `'cwd'` to make globs behave like explicit paths.

##### rename

Type: `string | Function`

Filename or function used to rename every file in `source`. Use a two-argument function to receive a frozen `source` file object and a mutable `destination` file object. The destination path must stay within the original destination directory. The legacy single-argument form is deprecated, emits a warning, and will be removed in the next major release.

```js
import cpy from 'cpy';

await cpy('foo.js', 'destination', {
	rename: (source, destination) => {
		if (source.nameWithoutExtension === 'foo') {
			destination.nameWithoutExtension = 'bar';
		}
	}
});

await cpy('foo.js', 'destination', {
	rename: (source, destination) => {
		if (source.nameWithoutExtension === 'foo') {
			destination.extension = 'ts';
		}

		console.log(destination.name);
		//=> 'foo.ts'
	}
});

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

##### concurrency

Type: `number`\
Default: `os.availableParallelism()`

Number of files being copied concurrently.

##### ignoreJunk

Type: `boolean`\
Default: `true`

Ignores [junk](https://github.com/sindresorhus/junk) files.

##### filter

Type: `Function`

Function to filter files to copy.

Receives a source file object and a context object with the resolved destination path.

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, {destinationPath}) => file.extension !== 'nocopy'
});
```

##### onProgress

Type: `Function`

The given function is called whenever there is measurable progress.

Note: Progress reporting makes copying slower, as it bypasses the faster filesystem copy path. Only pass this when you use it.

```js
import cpy from 'cpy';

await cpy('foo', 'destination', {
	onProgress: progress => {
		// …
	}
});
```

##### signal

Type: [`AbortSignal`](https://developer.mozilla.org/en-US/docs/Web/API/AbortSignal)

Abort signal to cancel the copy operation.

##### followSymbolicLinks

Type: `boolean`\
Default: `true`

Whether to follow symbolic links.

##### preserveTimestamps

Type: `boolean`\
Default: `false`

Preserve file access and modification timestamps when copying.

##### dryRun

Type: `boolean`\
Default: `false`

Skip copying and return the resolved destination paths.

##### 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.

##### Destination file object

###### path

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

Resolved destination path for the file. The directory part must stay within the original destination directory.

###### 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

The `onProgress` option provides progress information during file copying:

```js
import cpy from 'cpy';

await cpy(source, destination, {
	onProgress: progress => {
		console.log(`Progress: ${Math.round(progress.percent * 100)}%`);
	}
});
```

> [!NOTE]
> Progress reporting makes copying slower, as it bypasses the faster filesystem copy path. Only add a progress handler when you use it.

### Progress object

```js
{
	completedFiles: number,
	totalFiles: number,
	completedSize: number,
	percent: number,
	sourcePath: string,
	destinationPath: string,
}
```

- `completedFiles` - Number of files copied so far.
- `totalFiles` - Total number of files to copy.
- `completedSize` - Number of bytes copied so far.
- `percent` - Progress percentage as a value between `0` and `1`.
- `sourcePath` - Absolute source path of the current file being copied.
- `destinationPath` - Absolute destination path of the current file being copied.

#### handler(progress)

Type: `Function`

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](https://github.com/sindresorhus/cpy-cli) - CLI for this module
- [copy-file](https://github.com/sindresorhus/copy-file) - Copy a single file
- [move-file](https://github.com/sindresorhus/move-file) - Move a file
- [make-dir](https://github.com/sindresorhus/make-dir) - Make a directory and its parents if needed