grunt-zipup

grunt plugin to create a zip file with customisable/automatic package name and suffix.

License

Apache version 2. See the LICENSE file for more details.

Getting started

grunt-zipup has been tested on:

• Fedora 17 Linux (64bit)

• Windows 7 Enterprise (64bit)

You need Grunt ~0.4.1.

Install the grunt-zipup plugin in your project with:

npm install grunt-zipup --save-dev

Then add a line to your Gruntfile.js near the top:

module.exports = function (grunt) {
  grunt.loadNpmTasks('grunt-zipup');

  // ... rest of your grunt config ...
};

See the next section for options.

zipup task

The zipup task produces an output zip file with a default filename in the format:

<appName>_<version>_git@<commit ID>_YYYY-MM-DD_HHMMSS_<identifier>.<suffix>

The git and suffix parts are optional (see below for configuration).

You can also supply a custom filename template, which will be rendered using the data you supply in the task options. See the section on the template option, below.

Options

addGitCommitId

type: boolean, default: false

If the project is a git repo, set this to true to include the 7 character variant of the last commit ID as part of the filename.

For example, an output filename for appName "myapp" may look like:

myapp_git@4f7fe3f_2012-11-01_1151.zip

NB this requires that the git command be in your path.

appName

type: string, mandatory

The name of the application; used as the base filename for the zip file.

datetime

type: string, default: current datetime in format 'yyyy-mm-dd_HHMMss'

The date/time string to fill the datetime placeholder in the output zip file name template.

files

type: grunt files object, mandatory

Specifies which files to include in the output zip file. See grunt's API docs for details of the supported formats.

Some examples:

• Add three specific files to the zip file:

  files: [
    { src: 'src/app.js' },
    { src: 'src/data-adapter.js' },
    { src: 'src/ui.js' }
  ]
  

  Note that in this case, the destination file name in the zip file will match the source file name, including its parent directory hierarchy.

• Add all files under the app/src and app/lib directories, retaining the original paths to the matching files:

  file: [
    { src: 'app/src/**, expand: true },
    { src: 'app/src/**, expand: true },
  ]
  

• Zip all files inside the app/src and app/lib directories, keeping the same hierarchy in the zip file as is under those directories:

  files: [
    { cwd: 'app/src', src: '**', expand: true },
    { cwd: 'app/lib', src: '**', expand: true }
  ]
  

  Note how the cwd option is set so that the file paths used in the zip file are relative to those paths.

• Zip all files inside a directory, specifying a different output directory structure in the zip file:

  files: [
    { cwd: 'app/src', src: '**', expand: true, dest: 'src' },
    { cwd: 'app/lib', src: '**', expand: true, dest: 'lib' }
  ]
  

  If there is a file app/src/main.js in the project, this is translated to src/main.js in the output zip file.

outDir

type: string, default: '.'

Output directory to put the zipfile into.

suffix

type: string, default: 'zip'

The suffix for the zip file. Don't include the dot.

template

type: string, default: see below

The Mustache template string to use to generate the output zip file name.

The default for this is:

'{{appName}}_{{version}}_' +
'{{#gitCommit}}' +
'git@{{gitCommit}}_' +
'{{/gitCommit}}' +
'{{datetime}}{{identifier}}.{{suffix}}'

The data interpolated into the template string comes from the options for the zipup task (including any default values if the options aren't set). This means that it is possible to add extra data into the filename simply by adding new properties to a task configuration.

For example, this configuration:

zipup: {
  custom_filename: {
    appName: 'myapp',
    version: '0.1.0',
    datetime: grunt.template.today('yyyymmdd'),
    template: '{{appName}}_{{version}}_{{datetime}}_{{purpose}}.zip',

    // custom data to use in the template
    purpose: 'QA'
  }
}

produces filenames like:

myapp_0.1.0_20130708_QA.zip

Some properties are automatically generated by the zipup task, based on the current runtime environment. You can use these in your own custom templates:

• gitCommit is generated if addGitCommitId is set to true. It contains the abbreviated git commit ID for the project.

• identifier is a special option which is set at runtime. See the Tips section for details.

Aside: Why Mustache?

grunt has its own grunt.template functionality, so why am I using Mustache for this?

The reason is that grunt will pre-process configuration variables which contain lodash template strings. However, because the template for the zipup task is populated at runtime (particularly as the some of the variables are generated on the fly, like gitCommit), some of the template variables are undefined until that point. So the template string needs to be retained as is until the zipup task runs, at which point the correct data is available.

It may be that there's a way to protect lodash template strings in grunt config, but I haven't been able to find it.

version

type: string, mandatory

Application version.

Tips

Using data from package.json

Note that it can be useful to set some of the zipup options from your package.json. For example, your Gruntfile.js might look like this:

grunt.initConfig({
  packageInfo: grunt.file.readJSON('package.json'),

  // ... more config ...

  zipup: {
    wgt: {
      // set appName and version from package.json
      appName: '<%= packageInfo.name %>',
      version: '<%= packageInfo.version %>',

      suffix: 'wgt',
      addGitCommitId: true,
      files: [
        {
          cwd: 'build/dist',
          expand: true,
          src: '**'
        }
      ],
      outDir: 'build'
    }
  }
});

Using an identifier

To customise the output filename at runtime, you can pass an extra parameter to a zipup task when you invoke it. This extra parameter is added into the default template for the output filename, just before the file suffix.

For example, if a task is configured like this:

zipup: {
  package: {
    appName: 'myapp',
    version: '0.1.0'
  }
}

and you run that task with:

grunt zipup:package:FONT-CHANGES

you will produce a package with a name like:

app_0.1.0_2013-07-08_162941_FONT-CHANGES.zip

This can be useful to add on-the-fly explanations to a package name which don't really have a place in the main task configuration.

You can also provide a place for the identifier in your own custom template:

zipup: {
  package: {
    appName: 'myapp',
    version: '0.1.0',
    template: '{{appName}}_{{version}}{{identifier}}.zip'
  }
}

In situations where you don't supply an identifier, it is set to the empty string '' by default. If you do provide an identifier, it is automatically prefixed with '_', so you don't need to put that in your template.

Using zipup task data

The data used by the zipup task is retained on the grunt.zipup object, so it can be used by other tasks. This could be useful to get a handle on the name of the output zip file (for example), so you can reuse it in other tasks.

As an example of how to use it, the zipup project itself will print the data for one of the tasks when you run the test target, i.e.

grunt test

Here's an example of the output:

{
  "appName": "commit-id",
  "version": "0.3.0",
  "addGitCommitId": true,
  "files": [
    {
      "src": [
        "test/fixtures/specific-files/**"
      ],
      "expand": true
    }
  ],
  "outDir": "build",
  "identifier": "",
  "datetime": "2014-05-19_171011",
  "suffix": "zip",
  "template": "{{appName}}_{{version}}_{{#gitCommit}}git@{{gitCommit}}_{{/gitCommit}}{{datetime}}{{identifier}}.{{suffix}}",
  "gitCommit": "0cfe23f",
  "outfile": "build/commit-id_0.3.0_git@0cfe23f_2014-05-19_171011.zip"
}

Note the outfile property, which gives the path to the output zip file (relative to the Gruntfile).

Annotated example

grunt.initConfig({
  zipup: {
    wgt: {
      appName: 'TheMightyApp',
      suffix: 'wgt',
      version: '0.1.0',
      addGitCommitId: true,
      files: [
        {
          cwd: 'build/dist',
          src: '**',
          expand: true
        }
      ],
      outDir: 'build'
    }
  }
});

In this example, the zip file will be constructed as follows:

• Files files matching ** under the build/dist directory are added to the zip file.

• Inside the zip file, entries have the "build/dist" prefix stripped (as the cwd option is set); this means that the zip file structure will match the structure under the build/dist directory.

• The output zipfile name also contains the latest git commit ID and has the suffix "wgt".

• The zip file is written to the build/ directory. An example of the output filenames produced by this configuration might be:

  build/TheMightyApp_0.1.0_git@41513f9_2013-07-05_133951.wgt
  

Contributing

Please log issues on the github issue tracker for the project.

New features or bug fixes are welcome, and should be submitted as a pull request against the master branch of the project.

You should ensure that you run the grunt jshint task before submitting, to ensure that your code is lint free.

Also note that any changes you make should be accompanied by tests and documentation, and should not break the existing tests. The tests for the project require grunt-mochaccino to run. Install it and its dependencies the usual way:

npm install .

You can run the project tests with:

grunt test