@11ty/recursive-copy

A temporary fork of timkendrick/recursive-copy to satisfy https://github.com/11ty/eleventy/issues/3299 as Eleventy slowly moves to use Node native API fs.cp.

• v5.x requires Node 20+
• v4.x requires Node 18+
• v3.x requires Node 0.10+
• v2.x requires Node 0.10+

Simple, flexible file copy utility

Features

• Recursively copy whole directory hierarchies
• Choose which files are copied by passing a filter function, regular expression or glob
• Rename files dynamically, including changing the output path
• Transform file contents using streams
• Choose whether to overwrite existing files
• Choose whether to copy system files
• Filters out junk files by default
• Emits start, finish and error events for each file that is processed
• Optional promise-based interface

Examples

Node-style callback interface

var copy = require('@11ty/recursive-copy');

copy('src', 'dest', function(error, results) {
    if (error) {
        console.error('Copy failed: ' + error);
    } else {
        console.info('Copied ' + results.length + ' files');
    }
});

Promise interface

var copy = require('@11ty/recursive-copy');

copy('src', 'dest')
    .then(function(results) {
        console.info('Copied ' + results.length + ' files');
    })
    .catch(function(error) {
        console.error('Copy failed: ' + error);
    });

ES2015+ usage

import copy from '@11ty/recursive-copy';

try {
    const results = await copy('src', 'dest');
    console.info('Copied ' + results.length + ' files');
} catch (error) {
    console.error('Copy failed: ' + error);
}

Advanced options

var copy = require('@11ty/recursive-copy');

var path = require('path');
var through = require('through2');

var options = {
    overwrite: true,
    expand: true,
    dot: true,
    junk: true,
    filter: [
        '**/*',
        '!.htpasswd'
    ],
    rename: function(filePath) {
        return filePath + '.orig';
    },
    transform: function(src, dest, stats) {
        if (path.extname(src) !== '.txt') { return null; }
        return through(function(chunk, enc, done)  {
            var output = chunk.toString().toUpperCase();
            done(null, output);
        });
    }
};

copy('src', 'dest', options)
    .on(copy.events.COPY_FILE_START, function(copyOperation) {
        console.info('Copying file ' + copyOperation.src + '...');
    })
    .on(copy.events.COPY_FILE_COMPLETE, function(copyOperation) {
        console.info('Copied to ' + copyOperation.dest);
    })
    .on(copy.events.ERROR, function(error, copyOperation) {
        console.error('Unable to copy ' + copyOperation.dest);
    })
    .then(function(results) {
        console.info(results.length + ' file(s) copied');
    })
    .catch(function(error) {
        return console.error('Copy failed: ' + error);
    });

Usage

copy(src, dest, [options], [callback])

Recursively copy files and folders from src to dest

Arguments:

Returns:

Promise<Array> Promise, fulfilled with array of copy results:

[
    {
        "src": "/path/to/src",
        "dest": "/path/to/dest",
        "stats": <Stats>
    },
    {
        "src": "/path/to/src/file.txt",
        "dest": "/path/to/dest/file.txt",
        "stats": <Stats>
    },
    {
        "src": "/path/to/src/subfolder",
        "dest": "/path/to/dest/subfolder",
        "stats": <Stats>
    },
    {
        "src": "/path/to/src/subfolder/nested.txt",
        "dest": "/path/to/dest/subfolder/nested.txt",
        "stats": <Stats>
    }
]

copy.shouldCopy(filePath, [options])

Returns whether the dot and junk options keep a file, checked against its basename (filter is not applied).

copy.shouldCopy('src/.DS_Store', { dot: true }); // false
copy.shouldCopy('src/.htaccess', { dot: true }); // true

Events

The value returned by the copy function implements the EventEmitter interface, and emits the following events:

...where the types referred to in the handler signature are as follows:

ErrorInfo

CopyOperation