grunt-bg-shell
============

Improve your workflow by running commands in the background and in parallel using [Grunt](https://github.com/gruntjs/grunt). 

## Getting Started
*Note: This plugin requires Grunt `>=0.4.0`*

If you haven't used [Grunt](http://gruntjs.com/) before, be sure to check out the [Getting Started](http://gruntjs.com/getting-started) guide, as it explains how to create a [Gruntfile](http://gruntjs.com/sample-gruntfile) as well as install and use Grunt plugins. Once you're familiar with that process, you may install this plugin with this command:

```shell
npm install grunt-bg-shell --save-dev
```
Then add the task to your `Gruntfile.js` with this line:
```js
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:

```javascript
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
```javascript
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`](http://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback).
  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
```javascript
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:
```javascript
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
    }
  }
}
```