# @stackline/grunt-exec

> Grunt task for executing shell commands.

[![npm version](https://img.shields.io/npm/v/@stackline/grunt-exec.svg?style=flat-square)](https://www.npmjs.com/package/@stackline/grunt-exec)
[![license](https://img.shields.io/npm/l/@stackline/grunt-exec.svg?style=flat-square)](https://github.com/alexandroit/stackline-grunt-exec)
[![GitHub repository](https://img.shields.io/badge/GitHub-repository-181717?style=flat-square&logo=github)](https://github.com/alexandroit/stackline-grunt-exec)
[![Docs](https://img.shields.io/badge/docs-alexandro.net-0f766e?style=flat-square)](https://alexandro.net/docs/vanilla/grunt-exec/)
[![Reddit community](https://img.shields.io/badge/community-r%2FStackline-ff4500?style=flat-square&logo=reddit&logoColor=white)](https://www.reddit.com/r/Stackline/)

**[Documentation](https://alexandro.net/docs/vanilla/grunt-exec/)** | **[npm](https://www.npmjs.com/package/@stackline/grunt-exec)** | **[Issues](https://github.com/alexandroit/stackline-grunt-exec/issues)** | **[Repository](https://github.com/alexandroit/stackline-grunt-exec)**

**Current package version:** `1.0.2`

---

## Why this package?

`@stackline/grunt-exec` is the Stackline-maintained distribution of `grunt-exec@3.0.0`. It is an independent continuation of [grunt-exec](https://github.com/jharding/grunt-exec); original authors and licenses remain credited below.

## Compatibility

| Item | Value |
| :--- | :--- |
| Package | `@stackline/grunt-exec@1.0.2` |
| API target | `grunt-exec@3.0.0` |
| Supported Node.js | `>=0.8.0` |
| License | `MIT` |
| Main entry | `Gruntfile.js` |
| Runtime dependencies | `none` |
| Peer dependencies | `grunt >=0.4` |

## Installation

```bash
npm install @stackline/grunt-exec
```

Preserve existing imports and plugin resolution with an npm alias:

```bash
npm install grunt-exec@npm:@stackline/grunt-exec
```

## Usage and API reference

grunt-exec
==========

Grunt plugin for executing shell commands.


Installation
------------

Install grunt-exec using npm:

```
$ npm install @stackline/grunt-exec --save-dev
```

Then add this line to your project's *Gruntfile.js*:

```javascript
grunt.loadNpmTasks('@stackline/grunt-exec');
```

Usage
-----

This plugin is a [multi task][types_of_tasks], meaning that grunt will 
automatically iterate over all exec targets if a target is not specified.

If the exit code generated by the specified shell command is greater than 0, 
grunt-exec will assume an error has occurred and will abort grunt immediately.

[types_of_tasks]: http://gruntjs.com/configuring-tasks#task-configuration-and-targets

### Properties

*  __command__ (alias: __cmd__): The shell command to be executed. Must be a 
  string or a function that returns a string.
*  __stdin__: If `true`, stdin will be redirected from the child process to the current process allowing user interactivity (EXPERIMENTAL)
*  __stdout__: If `true`, stdout will be printed. Defaults to `true`.
*  __stderr__: If `true`, stderr will be printed. Defaults to `true`.
*  __cwd__: Current working directory of the shell command. Defaults to the 
  directory containing your Gruntfile.
*  __exitCode__ (alias: __exitCodes__): The expected exit code(s), task will 
  fail if the actual exit code doesn't match. Defaults to `0`. Can be an array 
  for multiple allowed exit codes.
*  __callback__: The callback function passed `child_process.exec`. Defaults to 
  a noop.
* __callbackArgs__: Additional arguments to pass to the callback. Defaults to empty array.
* __sync__: Whether to use `child_process.spawnSync`. Defaults to false.
* __options__: Options to provide to `child_process.exec`. [NodeJS Documentation](http://nodejs.org/api/child_process.html#child_process_child_process_exec_command_options_callback)
  - `cwd` String Current working directory of the child process
  - `env` Object Environment key-value pairs
  - `encoding` String *(Default: 'utf8')*
  - `shell` String Shell to execute the command with *(Default: '/bin/sh' on UNIX, 'cmd.exe' on Windows, The shell should understand the -c switch on UNIX or /s /c on Windows. On Windows, command line parsing should be compatible with cmd.exe.)*
  - `timeout` Number *(Default: 0)*
  - `maxBuffer` Number largest amount of data (in bytes) allowed on stdout or stderr - if exceeded child process is killed **(Default: 200*1024)**
  - `killSignal` String *(Default: 'SIGTERM')*
  - `uid` Number Sets the user identity of the process. (See [setuid(2)](http://man7.org/linux/man-pages/man2/setuid.2.html).)
  - `gid` Number Sets the group identity of the process. (See [setgid(2)](http://man7.org/linux/man-pages/man2/setgid.2.html).)

If the configuration is instead a simple `string`, it will be
interpreted as a full command itself:

```javascript
exec: {
  echo_something: 'echo "This is something"'
}
```

### Command Functions

If you plan on doing advanced stuff with grunt-exec, you'll most likely be using 
functions for the `command` property of your exec targets. This section details 
a couple of helpful tips about command functions that could help make your life 
easier.

#### Passing arguments from the command line

Command functions can be called with arbitrary arguments. Let's say we have the 
following exec target that echoes a formatted name:

```javascript
exec: {
  echo_name: {
    cmd: function(firstName, lastName) {
      var formattedName = [
        lastName.toUpperCase(),
        firstName.toUpperCase()
      ].join(', ');

      return 'echo ' + formattedName;
    }
  }
}
```

In order to get `SIMPSON, HOMER` echoed, you'd run 
`grunt exec:echo_name:homer:simpson` from the command line.

### Accessing `grunt` object

All command functions are called in the context of the `grunt` object that they 
are being ran with. This means you can access the `grunt` object through `this`.

### Example

The following examples are available in grunt-exec's Gruntfile.

```javascript
grunt.initConfig({
  exec: {
    remove_logs: {
      command: 'rm -f *.log',
      stdout: false,
      stderr: false
    },
    list_files: {
      cmd: 'ls -l **'
    },
    list_all_files: 'ls -la',
    echo_grunt_version: {
      cmd: function() { return 'echo ' + this.version; }
    },
    echo_name: {
      cmd: function(firstName, lastName) {
        var formattedName = [
          lastName.toUpperCase(),
          firstName.toUpperCase()
        ].join(', ');

        return 'echo ' + formattedName;
      }
    }
  }
});
```

Testing
-------

```
$ cd grunt-exec
$ npm test
```

Issues
------

Found a bug? Create an issue on GitHub.

https://github.com/jharding/grunt-exec/issues

Versioning
----------

For transparency and insight into the release cycle, releases will be numbered 
with the follow format:

`<major>.<minor>.<patch>`

And constructed with the following guidelines:

* Breaking backwards compatibility bumps the major
* New additions without breaking backwards compatibility bumps the minor
* Bug fixes and misc changes bump the patch

For more information on semantic versioning, please visit http://semver.org/.

License
-------

Original Copyright (c) 2012-2014 [Jake Harding](http://thejakeharding.com)
Copyright (c) 2016 grunt-exec
Licensed under the [MIT License](http://www.opensource.org/licenses/mit-license.php).

## Credits and original authors

- Original project: [grunt-exec](https://github.com/jharding/grunt-exec).
- Jake Harding.
- Graeme Wicksted.
- Stackline maintenance: [Alexandro Paixao Marques](https://www.linkedin.com/in/aleinfo/) and [Stackline contributors](https://github.com/alexandroit).

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

## License

`MIT`. See the license and notice files in the [repository](https://github.com/alexandroit/stackline-grunt-exec).

## Community and Links

- [Stackline website](https://alexandro.net/)
- [GitHub projects](https://github.com/alexandroit)
- [npm packages](https://www.npmjs.com/~alex360qc)
- [Reddit community — r/Stackline](https://www.reddit.com/r/Stackline/)
- [Maintainer LinkedIn](https://www.linkedin.com/in/aleinfo/)

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.