1# cross-spawn 2 3[![NPM version][npm-image]][npm-url] [![Downloads][downloads-image]][npm-url] [![Build Status][travis-image]][travis-url] [![Build status][appveyor-image]][appveyor-url] [![Dependency status][david-dm-image]][david-dm-url] [![Dev Dependency status][david-dm-dev-image]][david-dm-dev-url] 4 5[npm-url]:https://npmjs.org/package/cross-spawn 6[downloads-image]:http://img.shields.io/npm/dm/cross-spawn.svg 7[npm-image]:http://img.shields.io/npm/v/cross-spawn.svg 8[travis-url]:https://travis-ci.org/IndigoUnited/node-cross-spawn 9[travis-image]:http://img.shields.io/travis/IndigoUnited/node-cross-spawn/master.svg 10[appveyor-url]:https://ci.appveyor.com/project/satazor/node-cross-spawn 11[appveyor-image]:https://img.shields.io/appveyor/ci/satazor/node-cross-spawn/master.svg 12[david-dm-url]:https://david-dm.org/IndigoUnited/node-cross-spawn 13[david-dm-image]:https://img.shields.io/david/IndigoUnited/node-cross-spawn.svg 14[david-dm-dev-url]:https://david-dm.org/IndigoUnited/node-cross-spawn#info=devDependencies 15[david-dm-dev-image]:https://img.shields.io/david/dev/IndigoUnited/node-cross-spawn.svg 16 17A cross platform solution to node's spawn and spawnSync. 18 19 20## Installation 21 22`$ npm install cross-spawn` 23 24If you are using `spawnSync` on node 0.10 or older, you will also need to install `spawn-sync`: 25 26`$ npm install spawn-sync` 27 28 29## Why 30 31Node has issues when using spawn on Windows: 32 33- It ignores [PATHEXT](https://github.com/joyent/node/issues/2318) 34- It does not support [shebangs](http://pt.wikipedia.org/wiki/Shebang) 35- No `options.shell` support on node < v6 36- It does not allow you to run `del` or `dir` 37 38All these issues are handled correctly by `cross-spawn`. 39There are some known modules, such as [win-spawn](https://github.com/ForbesLindesay/win-spawn), that try to solve this but they are either broken or provide faulty escaping of shell arguments. 40 41 42## Usage 43 44Exactly the same way as node's [`spawn`](https://nodejs.org/api/child_process.html#child_process_child_process_spawn_command_args_options) or [`spawnSync`](https://nodejs.org/api/child_process.html#child_process_child_process_spawnsync_command_args_options), so it's a drop in replacement. 45 46 47```js 48var spawn = require('cross-spawn'); 49 50// Spawn NPM asynchronously 51var child = spawn('npm', ['list', '-g', '-depth', '0'], { stdio: 'inherit' }); 52 53// Spawn NPM synchronously 54var results = spawn.sync('npm', ['list', '-g', '-depth', '0'], { stdio: 'inherit' }); 55``` 56 57 58## Caveats 59 60#### `options.shell` as an alternative to `cross-spawn` 61 62Starting from node v6, `spawn` has a `shell` option that allows you run commands from within a shell. This new option solves most of the problems that `cross-spawn` attempts to solve, but: 63 64- It's not supported in node < v6 65- It has no support for shebangs on Windows 66- You must manually escape the command and arguments which is very error prone, specially when passing user input 67 68If you are using the `shell` option to spawn a command in a cross platform way, consider using `cross-spawn` instead. You have been warned. 69 70 71#### Shebangs 72 73While `cross-spawn` handles shebangs on Windows, its support is limited: e.g.: it doesn't handle arguments after the path, e.g.: `#!/bin/bash -e`. 74 75Remember to always test your code on Windows! 76 77 78## Tests 79 80`$ npm test` 81 82 83## License 84 85Released under the [MIT License](http://www.opensource.org/licenses/mit-license.php). 86
