README.md

grunt-bg-shell

Improve your workflow by running commands in the background and in parallel using Grunt.

Getting Started

Note: This plugin requires Grunt >=0.4.0

If you haven't used Grunt before, be sure to check out the Getting Started guide, as it explains how to create a Gruntfile 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-bg-shell --save-dev

Then add the task to your Gruntfile.js with this line:

grunt.loadNpmTasks('grunt-bg-shell');

Sample Usage

For example, say you want to run your node server and also compile coffeescript and sass/scss files all in the same terminal. You could acheive that with the following config:

module.exports = function (grunt) {
  grunt.initConfig({
    bgShell: {
      _defaults: {
        bg: true
      },
      
      watchCompass: {
        cmd: 'compass watch'
      },
      watchCoffee: {
        cmd: 'coffee --watch --output lib/ src/'
      },
      runNode: {
        cmd: 'node server.js',
        bg: false
      }
    }
  });
  grunt.registerTask('default', ['bgShell:watchCompass','bgShell:watchCoffee','bgShell:runNode']);
};

Available Options

bgShell: {
  lsTasks: {
    cmd: 'ls -la', // or function(){return 'ls -la'}
    execOpts: {
      cwd: './tasks'
    },
    stdout: true,
    stderr: true,
    bg: false,
    fail: false,
    done: function(){}
  }     
}

• cmd: command to execute or function(){} that returns a command to execute
• execOpts: options for child_process.exec. If execOpts.maxBuffer set to false, 0, NaN or Infinite it won't buffer stdout and stderr for done callback
• stdout: true, false or function(out){}
• stderr: true, false or function(err){}
• bg: background execution
• fail: fail grunt on error
• done: callback after execution function(err, stdout, stderr){}

Default Options

bgShell: {
  _defaults: {
    execOpts: {},
    stdout: true,
    stderr: true,
    bg: false,
    fail: false,
    done: function (err, stdout, stderr) {
    }
  },
}

Troubleshooting

If you get

Error: stdout maxBuffer exceeded

You should set execOpts.maxBuffer to false. But you won't get stdout and strerr in done callback

Example:

bgShell: {
  lsTasks: {
    cmd: 'ls -la',
    execOpts: {
      maxBuffer: false
    },
    stdout: function(chunk){
      // process your stdout chunk
    },
    stderr: function(chunk){
      // process your stderr chunk
    },
    done: function (err, stdout, stderr) {
      // stdout === null
      // stderr === null
    }
  }
}