metalsmith-cp-r

A Metalsmith plugin to copy files recursively. Similar to metalsmith-assets but:

• cp-r has minimal dependencies (only debug)
• cp-r offers several additional options and controls

Usage

Install as usual, npm install metalsmith-cp-r.

Javascript: use(metalsmith-cp-r(options))

CLI: You'll lose a few options since you can't pass functions.

Options

from: the contents of this directory, or this file, will be copied. Defaults to "_directory/assets" (see below).

to:      into this directory. It will be created if necessary. Defaults to "_destination/assets".

If from or to starts with _XXX/, they will be relative to that metalsmith property. Common ones are:

• _destination    see metalsmith.destination()
• _source          see metalsmith.source()
• _directory       see metalsmith.directory() or the constructor Metalsmith(__dirname)

Warning If you use this feature, you must use '/' (not a Windows '\\') as your folder delimiter.

e.g. to copy from the working directory into the folder you set in metalsmith.destination() use

{ from: "_directory/pathto/assets", to: "_destination/pathto/assets"}.

Otherwise, the path will be resolved normally using path.resolve(). (Sorry, if you really want to copy to or from a folder starting with _, the workaround is to start the path with a . or / or something...)

Less common options, all default to null

noclobber: if truthy, don't overwrite existing files. (Note: cp-r never overwrites existing folders)

dirMode     e.g. 0o777 copied dirs will have this "mode", default = use same mode as existing dir.

fileMode    e.g. 0o666 copied files will have this "mode", default = use same mode as existing file.

ignoreDir   a string or Regex, if present, ignore directories matching this pattern.

ignoreFile   a string or Regex, if present, ignore files matching this pattern.

Notes, Todos, and Caveats

cp-r doesn't do any fancy async stuff - didn't seem worth it for a simple build script. (It really feels "un-nody" because of all the synch stuff!)

cp-r has not been tested with links, locked directories, bad inputs, other weird stuff.

The "unit-test" is pretty lame. In package.json, please set scripts.test to the value for testWindows or testUnix as appropriate.

I wrote this because metalsmith-assets had a ton of obsolete dependencies and wasn't actively processing issues and pull requests. cp-r uses an absolute minimum of dependencies (only debug) and implements a few features from metalsmith-assets' feature requests.

metalsmith-assets-improved looks comparable.

metalsmith-copy-assets-540 isn't recursive.

It's possible that metalsmith-copy does this better.