Skip to content

sindresorhus/cpy

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

 

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
July 8, 2022 13:00
July 23, 2017 16:17
May 12, 2018 18:14
July 23, 2017 16:17
July 23, 2017 16:17
July 12, 2021 15:36
February 27, 2022 16:25
July 22, 2021 13:03
February 27, 2022 16:40
July 12, 2021 15:36
March 7, 2022 16:05
February 27, 2022 16:40

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

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

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

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.

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.

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.

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

cpy.on('progress', handler)

handler(progress)

Type: Function

progress
{
	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:

import cpy from 'cpy';

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

Related