grunt-contrib-copy

What is grunt-contrib-copy?

The grunt-contrib-copy package is a Grunt plugin that provides file copying capabilities. It allows you to copy files and directories from one location to another, which is useful for tasks such as preparing files for deployment, creating backups, or organizing project files.

What are grunt-contrib-copy's main functionalities?

Copying individual files

This feature allows you to copy a single file from a source location to a destination location. In this example, 'src/file1.txt' is copied to 'dest/file1.txt'.

{
  "copy": {
    "main": {
      "src": "src/file1.txt",
      "dest": "dest/file1.txt"
    }
  }
}

Copying multiple files

This feature allows you to copy multiple files by specifying an array of source and destination file paths. In this example, 'src/file1.txt' and 'src/file2.txt' are copied to 'dest/file1.txt' and 'dest/file2.txt' respectively.

{
  "copy": {
    "main": {
      "files": [
        {"src": "src/file1.txt", "dest": "dest/file1.txt"},
        {"src": "src/file2.txt", "dest": "dest/file2.txt"}
      ]
    }
  }
}

Copying entire directories

This feature allows you to copy entire directories, including all subdirectories and files. The 'expand' option is set to true to enable dynamic building of the destination paths. The 'cwd' option specifies the current working directory, and 'src' specifies the pattern to match files. In this example, all files and directories under 'src/' are copied to 'dest/'.

{
  "copy": {
    "main": {
      "expand": true,
      "cwd": "src/",
      "src": ["**"],
      "dest": "dest/"
    }
  }
}

Flattening directory structure

This feature allows you to flatten the directory structure when copying files. The 'flatten' option is set to true, which means all files will be copied directly into the destination directory without preserving the directory structure. In this example, all files under 'src/' are copied directly into 'dest/'.

{
  "copy": {
    "main": {
      "expand": true,
      "cwd": "src/",
      "src": ["**"],
      "dest": "dest/",
      "flatten": true
    }
  }
}

Other packages similar to grunt-contrib-copy

gulp-copy

gulp-copy is a Gulp plugin that provides similar file copying capabilities as grunt-contrib-copy. It allows you to copy files and directories using Gulp tasks. Compared to grunt-contrib-copy, gulp-copy is used within the Gulp task runner ecosystem, which may be preferred by developers who use Gulp for their build processes.

cpx

cpx is a command-line tool and library for copying files and directories. It supports advanced features such as watching for changes and copying only modified files. Compared to grunt-contrib-copy, cpx can be used both as a standalone CLI tool and as a library within Node.js scripts, providing more flexibility in different environments.

ncp

ncp (Node Copy) is a Node.js module for copying files and directories. It provides a simple API for recursive copying and supports various options for filtering and transforming files during the copy process. Compared to grunt-contrib-copy, ncp is a lower-level library that can be used directly in Node.js scripts without relying on a task runner like Grunt.

README

grunt-contrib-copy

Copy files and folders (part of the grunt-contrib collection). Submitted by Chris Talkington.

Recent Confusion

Many expect this task to work like cp on *nix systems but it was designed to use grunt conventions including the use of minimatch regex. We are working hard to make this and other tasks suitable for advanced users but there are no current plans to emulate cp.

Configuration

Inside your grunt.js file add a section named copy. This section specifies the files to copy.

Parameters

files object

This defines what files this task will copy and should contain key:value pairs.

The key (destination) should be an unique path (supports grunt.template) and the value (source) should be a filepath or an array of filepaths (supports minimatch).

As of v0.2.2, when copying to a directory you must add a trailing slash to the destination due to added support of single file copy.

options object

This controls how this task operates and should contain key:value pairs, see options below.

Options

basePath string

This option adjusts the folder structure when copied to the destination directory. When not explicitly set, best effort is made to locate the basePath by comparing all source filepaths left to right for a common pattern.

flatten boolean

This option performs a flat copy that dumps all the files into the root of the destination directory, overwriting files if they exist.

processName function

This option accepts a function that adjusts the filename of the copied file. Function is passed filename and should return a string.

options: {
  processName: function(filename) {
    if (filename == "test.jpg") {
      filename = "newname.jpg";
    }
    return filename;
  }
}

processContent function

This option is passed to grunt.file.copy as an advanced way to control the file contents that are copied.

processContentExclude string

This option is passed to grunt.file.copy as an advanced way to control which file contents are processed.

minimatch object

These options will be forwarded on to expandFiles, as referenced in the minimatch options section

Config Example

copy: {
  dist: {
    files: {
      "path/to/directory/": "path/to/source/*", // includes files in dir
      "path/to/directory/": "path/to/source/**", // includes files in dir and subdirs
      "path/to/project-<%= pkg.version %>/": "path/to/source/**", // variables in destination
      "path/to/directory/": ["path/to/sources/*.js", "path/to/more/*.js"], // include JS files in two diff dirs
      "path/to/filename.ext": "path/to/source.ext"
    }
  }
}

Release History

• 2012/08/10 - v0.2.0 - Refactored from grunt-contrib into individual repo.
• 2012/09/17 - v0.2.2 - single file copy support. test refactoring.