What does the "expand" option do in grunt-contrib-copy? The examples all use it but the docs say nothing about what it does

1. Here is the README and examples: https://github.com/gruntjs/grunt-contrib-copy/blob/master/README.md.
2. Here is the relevant part of the code (that I apparently cannot understand) from https://github.com/gruntjs/grunt-contrib-copy/blob/master/tasks/copy.js:

module.exports = function(grunt) {
  'use strict';

  var path = require('path');

  grunt.registerMultiTask('copy', 'Copy files.', function() {
    var kindOf = grunt.util.kindOf;

    var options = this.options({
      processContent: false,
      processContentExclude: []
    });

    var copyOptions = {
      process: options.processContent,
      noProcess: options.processContentExclude
    };

    grunt.verbose.writeflags(options, 'Options');

    var dest;
    var isExpandedPair;
    var tally = {
      dirs: 0,
      files: 0
    };

    this.files.forEach(function(filePair) {
      isExpandedPair = filePair.orig.expand || false;

      filePair.src.forEach(function(src) {
        if (detectDestType(filePair.dest) === 'directory') {
          dest = (isExpandedPair) ? filePair.dest : unixifyPath(path.join(filePair.dest, src));
        } else {
          dest = filePair.dest;
        }

        if (grunt.file.isDir(src)) {
          grunt.verbose.writeln('Creating ' + dest.cyan);
          grunt.file.mkdir(dest);
          tally.dirs++;
        } else {
          grunt.verbose.writeln('Copying ' + src.cyan + ' -> ' + dest.cyan);
          grunt.file.copy(src, dest, copyOptions);
          tally.files++;
        }
      });
    });

Solution 1:

Since expand is a part of Grunt, and not specific for grunt-contrib-copy, information about it can be found in Grunt's file configuration API:

Set expand to true to enable the following options:

• cwd All src matches are relative to (but don't include) this path.
• src Pattern(s) to match, relative to the cwd.
• dest Destination path prefix.
• ext Replace any existing extension with this value in generated dest paths.
• extDot Used to indicate where the period indicating the extension is located. Can take either 'first' (extension begins after the first period in the file name) or 'last' (extension begins after the last period), and is set by default to 'first'.
• flatten Remove all path parts from generated dest paths.
• rename This function is called for each matched src file, (after extension renaming and flattening). The dest and matched src path are passed in, and this function must return a new dest value. If the same dest is returned more than once, each src which used it will be added to an array of sources for it.

Additionally it seems like dest will always be considered to be a destination directory if setting expand to true.

Solution 2:

Expand lets you specify whether you want to create the destination path in full (e.g: /path/missing1/missing2), or only create the last directory when its parent exists (/path/existing/missing).