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 |
|
17 | A cross platform solution to node's spawn and spawnSync.
|
18 |
|
19 |
|
20 | ## Installation
|
21 |
|
22 | `$ npm install cross-spawn`
|
23 |
|
24 | If 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 |
|
31 | Node 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 |
|
38 | All these issues are handled correctly by `cross-spawn`.
|
39 | There 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 |
|
44 | Exactly 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
|
48 | var spawn = require('cross-spawn');
|
49 |
|
50 | // Spawn NPM asynchronously
|
51 | var child = spawn('npm', ['list', '-g', '-depth', '0'], { stdio: 'inherit' });
|
52 |
|
53 | // Spawn NPM synchronously
|
54 | var 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 |
|
62 | Starting 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 |
|
68 | If 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 |
|
73 | While `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 |
|
75 | Remember to always test your code on Windows!
|
76 |
|
77 |
|
78 | ## Tests
|
79 |
|
80 | `$ npm test`
|
81 |
|
82 |
|
83 | ## License
|
84 |
|
85 | Released under the [MIT License](http://www.opensource.org/licenses/mit-license.php).
|
86 |
|
\ | No newline at end of file |