grunt-contrib-watch - npm Package Compare versions

Comparing version 0.4.4 to 0.5.0

docs/watch-examples.md

@@ -44,4 +44,4 @@ # Examples
 });
-grunt.event.on('watch', function(action, filepath) {
-  grunt.log.writeln(filepath + ' has ' + action);
+grunt.event.on('watch', function(action, filepath, target) {
+  grunt.log.writeln(target + ': ' + filepath + ' has ' + action);
 });
@@ -158,2 +158,45 @@ ```
 
+### Rolling Your Own Live Reload
+Live reloading is made easy by the library [tiny-lr](https://github.com/mklabs/tiny-lr). It is encouraged to read the documentation for `tiny-lr`. If you would like to trigger the live reload server yourself, simply POST files to the URL: `http://localhost:35729/changed`. Or if you rather roll your own live reload implementation use the following example:
+
+```js
+// Create a live reload server instance
+var lrserver = require('tiny-lr')();
+
+// Listen on port 35729
+lrserver.listen(35729, function(err) { console.log('LR Server Started'); });
+
+// Then later trigger files or POST to localhost:35729/changed
+lrserver.changed({body:{files:['public/css/changed.css']}});
+```
+
+### Live Reload with Preprocessors
+Any time a watched file is edited with the `livereload` option enabled, the file will be sent to the live reload server. Some edited files you may desire to have sent to the live reload server, such as when preprocessing (`sass`, `less`, `coffeescript`, etc). As any file not recognized will reload the entire page as opposed to just the `css` or `javascript`.
+
+The solution is to point a `livereload` watch target to your destination files:
+
+```js
+grunt.initConfig({
+  sass: {
+    dev: {
+      src: ['src/sass/*.sass'],
+      dest: 'dest/css/index.css',
+    },
+  },
+  watch: {
+    sass: {
+      // We watch and compile sass files as normal but don't live reload here
+      files: ['src/sass/*.sass'],
+      tasks: ['sass'],
+    },
+    livereload: {
+      // Here we watch the files the sass task will compile to
+      // These files are sent to the live reload server after sass compiles to them
+      options: { livereload: true },
+      files: ['dest/**/*'],
+    },
+  },
+});
+```
+
 # FAQs
@@ -169,7 +212,9 @@
 
-## Why is the watch devouring all my memory?
-Likely because of an enthusiastic pattern trying to watch thousands of files. Such as `'**/*.js'` but forgetting to exclude the `node_modules` folder with `'!node_modules/**/*.js'`. Try grouping your files within a subfolder or be more explicit with your file matching pattern.
+## Why is the watch devouring all my memory/cpu?
+Likely because of an enthusiastic pattern trying to watch thousands of files. Such as `'**/*.js'` but forgetting to exclude the `node_modules` folder with `'!**/node_modules/**'`. Try grouping your files within a subfolder or be more explicit with your file matching pattern.
 
+Another reason if you're watching a large number of files could be the low default `interval`. Try increasing with `options: { interval: 5007 }`. Please see issues [#35](https://github.com/gruntjs/grunt-contrib-watch/issues/145) and [#145](https://github.com/gruntjs/grunt-contrib-watch/issues/145) for more information.
+
 ## Why spawn as child processes as a default?
-The goal of this watch task is as files are changed, run tasks as if they were triggered by the user themself. Each time a user runs `grunt` a process is spawned and tasks are ran in succession. In an effort to keep the experience consistent and continualy produce expected results, this watch task spawns tasks as child processes by default.
+The goal of this watch task is as files are changed, run tasks as if they were triggered by the user themself. Each time a user runs `grunt` a process is spawned and tasks are ran in succession. In an effort to keep the experience consistent and continually produce expected results, this watch task spawns tasks as child processes by default.
 
@@ -176,0 +221,0 @@ Sandboxing task runs also allows this watch task to run more stable over long periods of time. As well as more efficiently with more complex tasks and file structures.

docs/watch-options.md

@@ -15,7 +15,7 @@ # Settings
 
-## options.nospawn
+## options.spawn
 Type: `Boolean`
-Default: false
+Default: true
 
-This instructs the watch task to not spawn task runs in a child process. Setting this option also speeds up the reaction time of the watch (usually 500ms faster for most) and allows subsequent task runs to share the same context (i.e., using a reload task). Not spawning task runs can make the watch more prone to failing so please use as needed.
+Whether to spawn task runs in a child process. Setting this option to `false` speeds up the reaction time of the watch (usually 500ms faster for most) and allows subsequent task runs to share the same context. Not spawning task runs can make the watch more prone to failing so please use as needed.
 
@@ -27,5 +27,5 @@ Example:
     files: ['**/*.js'],
-    tasks: ['livereload'],
+    tasks: ['jshint'],
     options: {
-      nospawn: true,
+      spawn: false,
     },
@@ -36,2 +36,4 @@ },
 
+*For backwards compatibility the option `nospawn` is still available and will do the opposite of `spawn`.*
+
 ## options.interrupt
@@ -106,2 +108,28 @@ Type: `Boolean`
 
+## options.dateFormat
+Type: `Function`
+
+This is *only a task level option* and cannot be configured per target. By default when the watch has finished running tasks it will display the message `Completed in 1.301s at Thu Jul 18 2013 14:58:21 GMT-0700 (PDT) - Waiting...`. You can override this message by supplying your own function:
+
+```js
+watch: {
+  options: {
+    dateFormat: function(time) {
+      grunt.log.writeln('The watch finished in ' + time + 'ms at' + (new Date()).toString()));
+      grunt.log.writeln('Waiting for more changes...');
+    },
+  },
+  scripts: {
+    files: '**/*.js',
+    tasks: 'jshint',
+  },
+},
+```
+
+## options.atBegin
+Type: `Boolean`
+Default: false
+
+This option will trigger the run of each specified task at startup of the watcher.
+
 ## options.livereload
@@ -108,0 +136,0 @@ Type: `Boolean|Number|Object`

Gruntfile.js

@@ -5,5 +5,4 @@ /*
  *
- * Copyright (c) 2012 "Cowboy" Ben Alman, contributors
+ * Copyright (c) 2013 "Cowboy" Ben Alman, contributors
  * Licensed under the MIT license.
- * https://github.com/gruntjs/grunt-contrib-watch/blob/master/LICENSE-MIT
  */
@@ -14,4 +13,2 @@
 module.exports = function(grunt) {
-
-  // Project configuration.
   grunt.initConfig({
@@ -28,4 +25,2 @@ jshint: {
     },
-
-    // Watch
     watch: {
@@ -37,14 +32,15 @@ all: {
     },
-
-    // Unit tests.
     nodeunit: {
       tests: ['test/tasks/*_test.js']
     }
+  });
 
+  // Dynamic alias task to nodeunit. Run individual tests with: grunt test:events
+  grunt.registerTask('test', function(file) {
+    grunt.config('nodeunit.tests', String(grunt.config('nodeunit.tests')).replace('*', file || '*'));
+    grunt.task.run('nodeunit');
   });
 
-  // Actually load this plugin's task(s).
   grunt.loadTasks('tasks');
 
-  // These plugins provide necessary tasks.
   grunt.loadNpmTasks('grunt-contrib-jshint');
@@ -54,5 +50,3 @@ grunt.loadNpmTasks('grunt-contrib-nodeunit');
 
-  // By default, lint and run all tests.
   grunt.registerTask('default', ['jshint', 'nodeunit', 'build-contrib']);
-
 };

package.json

 {
   "name": "grunt-contrib-watch",
   "description": "Run predefined tasks whenever watched file patterns are added, changed or deleted.",
-  "version": "0.4.4",
+  "version": "0.5.0",
   "homepage": "https://github.com/gruntjs/grunt-contrib-watch",
@@ -31,3 +31,3 @@ "author": {
   "dependencies": {
-    "gaze": "~0.3.4",
+    "gaze": "~0.4.0",
     "tiny-lr": "0.0.4"
@@ -34,0 +34,0 @@ },

README.md

@@ -43,7 +43,7 @@ # grunt-contrib-watch [![Build Status](https://travis-ci.org/gruntjs/grunt-contrib-watch.png?branch=master)](https://travis-ci.org/gruntjs/grunt-contrib-watch)
 
-#### options.nospawn
+#### options.spawn
 Type: `Boolean`
-Default: false
+Default: true
 
-This instructs the watch task to not spawn task runs in a child process. Setting this option also speeds up the reaction time of the watch (usually 500ms faster for most) and allows subsequent task runs to share the same context (i.e., using a reload task). Not spawning task runs can make the watch more prone to failing so please use as needed.
+Whether to spawn task runs in a child process. Setting this option to `false` speeds up the reaction time of the watch (usually 500ms faster for most) and allows subsequent task runs to share the same context. Not spawning task runs can make the watch more prone to failing so please use as needed.
 
@@ -55,5 +55,5 @@ Example:
     files: ['**/*.js'],
-    tasks: ['livereload'],
+    tasks: ['jshint'],
     options: {
-      nospawn: true,
+      spawn: false,
     },
@@ -64,2 +64,4 @@ },
 
+*For backwards compatibility the option `nospawn` is still available and will do the opposite of `spawn`.*
+
 #### options.interrupt
@@ -134,2 +136,28 @@ Type: `Boolean`
 
+#### options.dateFormat
+Type: `Function`
+
+This is *only a task level option* and cannot be configured per target. By default when the watch has finished running tasks it will display the message `Completed in 1.301s at Thu Jul 18 2013 14:58:21 GMT-0700 (PDT) - Waiting...`. You can override this message by supplying your own function:
+
+```js
+watch: {
+  options: {
+    dateFormat: function(time) {
+      grunt.log.writeln('The watch finished in ' + time + 'ms at' + (new Date()).toString()));
+      grunt.log.writeln('Waiting for more changes...');
+    },
+  },
+  scripts: {
+    files: '**/*.js',
+    tasks: 'jshint',
+  },
+},
+```
+
+#### options.atBegin
+Type: `Boolean`
+Default: false
+
+This option will trigger the run of each specified task at startup of the watcher.
+
 #### options.livereload
@@ -199,4 +227,4 @@ Type: `Boolean|Number|Object`
 });
-grunt.event.on('watch', function(action, filepath) {
-  grunt.log.writeln(filepath + ' has ' + action);
+grunt.event.on('watch', function(action, filepath, target) {
+  grunt.log.writeln(target + ': ' + filepath + ' has ' + action);
 });
@@ -313,2 +341,45 @@ ```
 
+##### Rolling Your Own Live Reload
+Live reloading is made easy by the library [tiny-lr](https://github.com/mklabs/tiny-lr). It is encouraged to read the documentation for `tiny-lr`. If you would like to trigger the live reload server yourself, simply POST files to the URL: `http://localhost:35729/changed`. Or if you rather roll your own live reload implementation use the following example:
+
+```js
+// Create a live reload server instance
+var lrserver = require('tiny-lr')();
+
+// Listen on port 35729
+lrserver.listen(35729, function(err) { console.log('LR Server Started'); });
+
+// Then later trigger files or POST to localhost:35729/changed
+lrserver.changed({body:{files:['public/css/changed.css']}});
+```
+
+##### Live Reload with Preprocessors
+Any time a watched file is edited with the `livereload` option enabled, the file will be sent to the live reload server. Some edited files you may desire to have sent to the live reload server, such as when preprocessing (`sass`, `less`, `coffeescript`, etc). As any file not recognized will reload the entire page as opposed to just the `css` or `javascript`.
+
+The solution is to point a `livereload` watch target to your destination files:
+
+```js
+grunt.initConfig({
+  sass: {
+    dev: {
+      src: ['src/sass/*.sass'],
+      dest: 'dest/css/index.css',
+    },
+  },
+  watch: {
+    sass: {
+      // We watch and compile sass files as normal but don't live reload here
+      files: ['src/sass/*.sass'],
+      tasks: ['sass'],
+    },
+    livereload: {
+      // Here we watch the files the sass task will compile to
+      // These files are sent to the live reload server after sass compiles to them
+      options: { livereload: true },
+      files: ['dest/**/*'],
+    },
+  },
+});
+```
+
 ### FAQs
@@ -324,7 +395,9 @@
 
-#### Why is the watch devouring all my memory?
-Likely because of an enthusiastic pattern trying to watch thousands of files. Such as `'**/*.js'` but forgetting to exclude the `node_modules` folder with `'!node_modules/**/*.js'`. Try grouping your files within a subfolder or be more explicit with your file matching pattern.
+#### Why is the watch devouring all my memory/cpu?
+Likely because of an enthusiastic pattern trying to watch thousands of files. Such as `'**/*.js'` but forgetting to exclude the `node_modules` folder with `'!**/node_modules/**'`. Try grouping your files within a subfolder or be more explicit with your file matching pattern.
 
+Another reason if you're watching a large number of files could be the low default `interval`. Try increasing with `options: { interval: 5007 }`. Please see issues [#35](https://github.com/gruntjs/grunt-contrib-watch/issues/145) and [#145](https://github.com/gruntjs/grunt-contrib-watch/issues/145) for more information.
+
 #### Why spawn as child processes as a default?
-The goal of this watch task is as files are changed, run tasks as if they were triggered by the user themself. Each time a user runs `grunt` a process is spawned and tasks are ran in succession. In an effort to keep the experience consistent and continualy produce expected results, this watch task spawns tasks as child processes by default.
+The goal of this watch task is as files are changed, run tasks as if they were triggered by the user themself. Each time a user runs `grunt` a process is spawned and tasks are ran in succession. In an effort to keep the experience consistent and continually produce expected results, this watch task spawns tasks as child processes by default.
 
@@ -338,2 +411,3 @@ Sandboxing task runs also allows this watch task to run more stable over long periods of time. As well as more efficiently with more complex tasks and file structures.
 
+ * 2013-07-18   v0.5.0   Added target name to watch event. Added atBegin option to run tasks when watcher starts. Changed nospawn option to spawn (nospawn still available for backwards compatibility). Moved libs/vars into top scope to prevent re-init. Bumped Gaze version to ~0.4. Re-grab task/target options upon each task run. Add dateFormat option to override the date/time output upon completion.
  * 2013-05-27   v0.4.4   Remove gracefully closing SIGINT. Not needed and causes problems for Windows. Ensure tasks are an array to not conflict with cliArgs.
@@ -360,2 +434,2 @@ * 2013-05-11   v0.4.3   Only group changed files per target to send correct files to live reload.
 
-*This file was generated on Mon May 27 2013 11:50:43.*
+*This file was generated on Thu Jul 18 2013 20:14:03.*

tasks/lib/taskrun.js

@@ -46,3 +46,3 @@ /*
 
-    if (self.options.nospawn === true) {
+    if (self.options.spawn === false || self.options.nospawn === true) {
       grunt.task.run(self.tasks);
@@ -60,3 +60,3 @@ done();
         // Run grunt this process uses, append the task to be run and any cli options
-        args: self.tasks.concat(self.options.cliArgs || [])
+        args: self.tasks.concat(self.options.cliArgs || []),
       }, function(err, res, code) {
@@ -63,0 +63,0 @@ // Spawn is done

tasks/lib/taskrunner.js

@@ -90,3 +90,17 @@ /*
     // Return the targets normalized
-    return self._getTargets(self.name);
+    var targets = self._getTargets(self.name);
+
+    // Check whether target's tasks should run at start w/ atBegin option
+    if (self.running === false) {
+      self.queue = targets.filter(function(tr) {
+        return tr.options.atBegin === true && tr.tasks.length > 0;
+      }).map(function(tr) {
+        return tr.name;
+      });
+      if (self.queue.length > 0) {
+        self.run();
+      }
+    }
+
+    return targets;
   };
@@ -138,2 +152,5 @@
 
+    // Re-grab task options in case they changed between runs
+    self.options = grunt.config([self.name, 'options']) || {};
+
     // If we should interrupt
@@ -169,3 +186,9 @@ if (self.running === true) {
       if (!tr) { return next(); }
-      if (tr.options.nospawn) { shouldComplete = false; }
+
+      // Re-grab options in case they changed between runs
+      tr.options = grunt.util._.defaults(grunt.config([self.name, name, 'options']) || {}, self.options);
+
+      if (tr.options.spawn === false || tr.options.nospawn === true) {
+        shouldComplete = false;
+      }
       tr.run(next);
@@ -209,3 +232,4 @@ }, function() {
     var time = 0;
-    self.queue.forEach(function(name, i) {
+    for (var i = 0, len = self.queue.length; i < len; ++i) {
+      var name = self.queue[i];
       var target = self.targets[name];
@@ -215,3 +239,4 @@ if (!target) { return; }
         time += target.complete();
-        self.queue[i] = null;
+        self.queue.splice(i--, 1);
+        len--;
 
@@ -224,3 +249,3 @@ // if we're just livereloading and no tasks
       }
-    });
+    }
     var elapsed = (time > 0) ? Number(time / 1000) : 0;
@@ -227,0 +252,0 @@ self.changedFiles = Object.create(null);

tasks/watch.js

@@ -9,12 +9,22 @@ /*
 
+var path = require('path');
+var Gaze = require('gaze').Gaze;
+var waiting = 'Waiting...';
+var changedFiles = Object.create(null);
+var watchers = [];
+
 module.exports = function(grunt) {
   'use strict';
 
-  var path = require('path');
-  var Gaze = require('gaze').Gaze;
   var taskrun = require('./lib/taskrunner')(grunt);
 
-  var waiting = 'Waiting...';
-  var changedFiles = Object.create(null);
-  var watchers = [];
+  // Default date format logged
+  var dateFormat = function(time) {
+    grunt.log.writeln(String(
+      'Completed in ' +
+      time.toFixed(3) +
+      's at ' +
+      (new Date()).toString()
+    ).cyan + ' - ' + waiting);
+  };
 
@@ -36,8 +46,3 @@ // When task runner has started
     if (time > 0) {
-      grunt.log.writeln(String(
-        'Completed in ' +
-        time.toFixed(3) +
-        's at ' +
-        (new Date()).toString()
-      ).cyan + ' - ' + waiting);
+      dateFormat(time);
     }
@@ -62,3 +67,3 @@ });
     // Close any previously opened watchers
-    watchers.forEach(function(watcher, i) {
+    watchers.forEach(function(watcher) {
       watcher.close();
@@ -73,2 +78,8 @@ });
 
+    // If a custom dateFormat function
+    var df = grunt.config([name, 'options', 'dateFormat']);
+    if (typeof df === 'function') {
+      dateFormat = df;
+    }
+
     if (taskrun.running === false) { grunt.log.write(waiting); }
@@ -80,2 +91,4 @@
       nospawn: false,
+      spawn: true,
+      atBegin: false,
       event: ['all'],
@@ -135,3 +148,3 @@ target: target,
           if (grunt.event.listeners('watch').length > 0) {
-            grunt.event.emit('watch', status, filepath);
+            grunt.event.emit('watch', status, filepath, target.name);
           }
@@ -138,0 +151,0 @@

test/fixtures/events/Gruntfile.js

@@ -32,3 +32,5 @@ module.exports = function(grunt) {
         files: ['lib/*.js'],
-      }
+      },
+      targetOne: { files: ['lib/one/*.js'] },
+      targetTwo: { files: ['lib/two/*.js'] },
     },
@@ -40,6 +42,10 @@ });
 
+  var timeout;
+
   // trigger on watch events
-  var timeout;
-  grunt.event.on('watch', function(action, filepath) {
+  grunt.event.on('watch', function(action, filepath, target) {
     grunt.log.writeln(filepath + ' was indeed ' + action);
+    if (target !== undefined) {
+      grunt.log.writeln(target + ' specifc event was fired')
+    }
     clearTimeout(timeout);
@@ -50,2 +56,3 @@ timeout = setTimeout(function() {
   });
+
 };

test/fixtures/fail/Gruntfile.js

@@ -7,3 +7,3 @@ module.exports = function(grunt) {
       options: {
-        nospawn: true,
+        spawn: false,
       },
@@ -10,0 +10,0 @@ warn: {

test/fixtures/livereload/Gruntfile.js

@@ -28,3 +28,3 @@ module.exports = function(grunt) {
         options: {
-          nospawn: true,
+          spawn: false,
           livereload: 1337,
@@ -31,0 +31,0 @@ },

test/fixtures/multiTargets/Gruntfile.js

@@ -9,3 +9,3 @@ module.exports = function(grunt) {
       interrupt: { message: 'I want to be interrupted', wait: 5000 },
-      fail: { fail: 1, message: 'This task should fail' }
+      fail: { fail: 1, message: 'This task should fail', wait: 1000 }
     },
@@ -12,0 +12,0 @@ watch: {

test/fixtures/patterns/Gruntfile.js

@@ -7,3 +7,3 @@ module.exports = function(grunt) {
       negate: {
-        files: ['**/*.js', '!lib/sub/*.js'],
+        files: ['lib/**/*.js', '!lib/sub/*.js'],
         tasks: ['echo'],
@@ -10,0 +10,0 @@ },

test/tasks/events_test.js

@@ -113,2 +113,22 @@ 'use strict';
   },
+  targetSpecific: function(test) {
+    test.expect(2);
+    var cwd = path.resolve(fixtures, 'events');
+    var assertWatch = helper.assertTask('watch', {cwd: cwd});
+    assertWatch([function() {
+      var write = 'var test = false;';
+      setTimeout(function() {
+        grunt.file.write(path.join(cwd, 'lib/one', 'test.js'), write);
+      }, 300);
+      setTimeout(function() {
+        grunt.file.write(path.join(cwd, 'lib/two', 'test.js'), write);
+      }, 300);
+    }], function(result) {
+      result = helper.unixify(result);
+      helper.verboseLog(result);
+      test.ok(result.indexOf('lib/one/test.js was indeed changed\ntargetOne specifc event was fired') !== -1, 'event should have been emitted with targetOne specified');
+      test.ok(result.indexOf('lib/two/test.js was indeed changed\ntargetTwo specifc event was fired') !== -1, 'event should have been emitted with targetTwo specified');
+      test.done();
+    });
+  }
 };

test/tasks/helper.js

@@ -103,4 +103,3 @@ var grunt = require('grunt');
 helper.unixify = function(str) {
-  str = grunt.util.normalizelf(str);
-  return str.replace(/\\/g, '/');
+  return str.replace(/\\/g, '/').replace(/\r\n|\n/g, '\n');
 };

test/tasks/watch_test.js

@@ -9,3 +9,3 @@ 'use strict';
 var fixtures = helper.fixtures;
-var useFixtures = ['multiTargets', 'oneTarget'];
+var useFixtures = ['multiTargets', 'oneTarget', 'atBegin', 'dateFormat'];
 
@@ -18,3 +18,3 @@ function cleanUp() {
 
-exports.watchConfig = {
+exports.watch = {
   setUp: function(done) {
@@ -31,2 +31,27 @@ cleanUp();
   },
+  atBegin: function(test) {
+    test.expect(1);
+    var cwd = path.resolve(fixtures, 'atBegin');
+    var assertWatch = helper.assertTask(['watch', '--debug'], {cwd:cwd});
+    assertWatch(function() {
+       // noop. Does not modify any watched files.
+    }, function(result) {
+      helper.verboseLog(result);
+      var firstIndex = result.indexOf('one has changed');
+      test.ok(firstIndex !== -1, 'Watch should have fired even though no file was changed.');
+      test.done();
+    });
+  },
+  dateFormat: function(test) {
+    test.expect(1);
+    var cwd = path.resolve(fixtures, 'dateFormat');
+    var assertWatch = helper.assertTask(['watch', '--debug'], {cwd:cwd});
+    assertWatch(function() {
+       grunt.file.write(path.join(cwd, 'lib', 'one.js'), 'var one = true;');
+    }, function(result) {
+      helper.verboseLog(result);
+      test.ok(result.indexOf('dateFormat has worked!') !== -1, 'Should have displayed a custom dateFormat.');
+      test.done();
+    });
+  },
   oneTarget: function(test) {
@@ -33,0 +58,0 @@ test.expect(2);

New alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Fixed alerts

License Policy Violation

License

This package is not allowed per your license policy. Review the package's license to ensure compliance.

Found 1 instance in 1 package

Improved metrics

Total package byte prevSize

93499

increased by13.37%

Number of package files

56

increased by12%

Lines of code

1634

increased by8.21%

Number of lines in readme file

427

increased by20.96%

Dependency changes

• + Addedgaze@0.4.3(transitive)

• + Addedglobule@0.1.0(transitive)

• + Addedlodash@1.0.2(transitive)

• - Removedfileset@0.1.8(transitive)

• - Removedgaze@0.3.4(transitive)

• Updatedgaze@~0.4.0