Add CHOKIDAR_USEPOLLING env variable detection

To override the chokidar instance configuration for an entire
stack at once, regardless of how it is used / dependency depth.

Have to do string comparison because process.env always sets variables
as strings. Going to restrict the possible options to keep documenting
and reasoning simple.

Author: Evan Jacobs

index.js

@@ -90,6 +90,18 @@ function FSWatcher(_opts) {
     opts.usePolling = process.platform === 'darwin';
   }
 
+  // Global override (useful for end-developers that need to force polling for all
+  // instances of chokidar, regardless of usage/dependency depth)
+  if (process.env.CHOKIDAR_USEPOLLING !== undefined) {
+    var envLower = process.env.CHOKIDAR_USEPOLLING.toLowerCase();
+
+    if (envLower === 'false' || envLower === '0') {
+      opts.usePolling = false;
+    } else if (envLower === 'true' || envLower === '1') {
+      opts.usePolling = true;
+    }
+  }
+
   // Editor atomic write normalization enabled by default with fs.watch
   if (undef('atomic')) opts.atomic = !opts.usePolling && !opts.useFsEvents;
   if (opts.atomic) this._pendingUnlinks = Object.create(null);

test.js

@@ -1765,4 +1765,61 @@ function runTests(baseopts) {
       });
     });
   });
+  describe('env variable option override', function() {
+    describe('CHOKIDAR_USEPOLLING', function() {
+      afterEach(function() {
+        delete process.env.CHOKIDAR_USEPOLLING;
+      });
+
+      it('should make options.usePolling `true` when CHOKIDAR_USEPOLLING is set to true', function(done) {
+        options.usePolling = false;
+        process.env.CHOKIDAR_USEPOLLING = true;
+
+        watcher = chokidar.watch(fixturesPath, options).on('ready', function() {
+          watcher.options.usePolling.should.be.true;
+          done();
+        });
+      });
+
+      it('should make options.usePolling `true` when CHOKIDAR_USEPOLLING is set to 1', function(done) {
+        options.usePolling = false;
+        process.env.CHOKIDAR_USEPOLLING = 1;
+
+        watcher = chokidar.watch(fixturesPath, options).on('ready', function() {
+          watcher.options.usePolling.should.be.true;
+          done();
+        });
+      });
+
+      it('should make options.usePolling `false` when CHOKIDAR_USEPOLLING is set to false', function(done) {
+        options.usePolling = true;
+        process.env.CHOKIDAR_USEPOLLING = false;
+
+        watcher = chokidar.watch(fixturesPath, options).on('ready', function() {
+          watcher.options.usePolling.should.be.false;
+          done();
+        });
+      });
+
+      it('should make options.usePolling `false` when CHOKIDAR_USEPOLLING is set to 0', function(done) {
+        options.usePolling = true;
+        process.env.CHOKIDAR_USEPOLLING = false;
+
+        watcher = chokidar.watch(fixturesPath, options).on('ready', function() {
+          watcher.options.usePolling.should.be.false;
+          done();
+        });
+      });
+
+      it('should not attenuate options.usePolling when CHOKIDAR_USEPOLLING is set to an arbitrary value', function(done) {
+        options.usePolling = true;
+        process.env.CHOKIDAR_USEPOLLING = 'foo';
+
+        watcher = chokidar.watch(fixturesPath, options).on('ready', function() {
+          watcher.options.usePolling.should.be.true;
+          done();
+        });
+      });
+    });
+  });
 }