grunt-newer

Configure Grunt tasks to run with only those files modified since the last successful run.

Getting Started

This plugin requires Grunt ~0.4.1

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a gruntfile.js as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

npm install grunt-newer --save-dev

Once the plugin has been installed, it may be enabled inside your gruntfile.js with this line:

grunt.loadNpmTasks('grunt-newer');

The `newer` task

The newer task doesn't require any special configuration. To use it, just add newer as the first argument when running other tasks.

For example, if you want to run JSHint on only those files that have been modified since the last successful run, configure the jshint task as you would otherwise, and then register a task with newer at the front.

  grunt.initConfig({
    jshint: {
      options: {
        jshintrc: '.jshintrc'
      },
      all: {
        src: 'src/**/*.js'
      }
    }
  });

  grunt.loadNpmTasks('grunt-contrib-jshint');
  grunt.loadNpmTasks('grunt-newer');

  grunt.registerTask('lint', ['newer:jshint:all']);

With the above configuration, running grunt lint will configure your jshint:all task to use only files in the src config that have been modified since the last successful run of the same task.

Another example is to use the newer task in conjunction with watch. For example, you might want to set up a watch to run a linter on all your .js files whenever any of them changes. With the newer task, instead of re-running the linter on all files, you only need to run it on the files that changed.

  var srcFiles = 'src/**/*.js';

  grunt.initConfig({
    jshint: {
      all: {
        src: srcFiles
      }
    },
    watch: {
      all: {
        files: srcFiles,
        tasks: ['newer:jshint:all']
      }
    }
  });

  grunt.loadNpmTasks('grunt-contrib-jshint');
  grunt.loadNpmTasks('grunt-contrib-watch');
  grunt.loadNpmTasks('grunt-newer');

With the above configuration, running grunt jshint watch will first lint all your files with jshint and then set up a watch. Whenever one of your source files changes, the jshint task will be run on just the modified file.

The `any-newer` task

The newer task described above reconfigures the target task to run with only those files that have been modified since the last run. This works well for tasks that don't generate new files (like linting). When you have a task that generates destination files based on configured source files, you likely want to process all source files if any one of them has been modified since the last run. The any-newer task serves this purpose.

For example, if you want to run UglifyJS on all your source files only when one or more have been modified since the last run, configure the uglify task as you would otherwise, and then register a task with any-newer at the front.

  grunt.initConfig({
    uglify: {
      all: {
        files: {
          'dest/app.min.js': 'src/**/*.js'
        }
      }
    }
  });

  grunt.loadNpmTasks('grunt-contrib-uglify');
  grunt.loadNpmTasks('grunt-newer');

  grunt.registerTask('minify', ['any-newer:uglify:all']);

With the above configuration, running grunt minify will only run the uglify:all task if one or more of the configured src files have been modified since the last successful run of the same task.

Options for the `newer` and `any-newer` tasks

In most cases, you shouldn't need to add any special configuration for the newer or any-newer tasks. Just grunt.loadNpmTasks('grunt-newer') and you can use the tasks. The single option below is available if you need a custom configuration.

options.timestamps

type: string
default: node_modules/grunt-newer/.cache

To keep track of timestamps for successful runs, the newer and any-newer tasks write to a cache directory. The default is to use a .cache directory within the grunt-newer installation directory. If you need timestamp info to be written to a different location, configure the task with a timestamps option.

Example use of the timestamps option:

  grunt.initConfig({
    newer: {
      options: {
        timestamps: 'path/to/custom/cache/directory'
      }
    }
  });

That's it

Please submit an issue if you encounter any trouble. Contributions or suggestions for improvements welcome!

russelldavis/grunt-newer