exec async now returns child proc obj

README.md

@@ -322,12 +322,17 @@ Examples:
 
 ```javascript
 var version = exec('node --version', {silent:true}).output;
+
+var child = exec('some_long_running_process', {async:true});
+child.stdout.on('data', function(data) { 
+  /* ... do something with data ... */ 
+});
 ```
 
 Executes the given `command` _synchronously_, unless otherwise specified. 
 When in synchronous mode returns the object `{ code:..., output:... }`, containing the program's 
-`output` (stdout + stderr)  and its exit `code`. Otherwise the `callback` gets the 
-arguments `(code, output)`.
+`output` (stdout + stderr)  and its exit `code`. Otherwise returns the child process object, and
+the `callback` gets the arguments `(code, output)`.
 
 **Note:** For long-lived processes, it's best to run `exec()` asynchronously as
 the current synchronous implementation uses a lot of CPU. This should be getting
@@ -372,4 +377,3 @@ Returns true if all the given paths exist.
 _This function is being deprecated. Use `silent(false) instead.`_
 
 Enables all output (default)
-

shell.js

@@ -812,12 +812,17 @@ exports.env = process.env;
 //@
 //@ ```javascript
 //@ var version = exec('node --version', {silent:true}).output;
+//@
+//@ var child = exec('some_long_running_process', {async:true});
+//@ child.stdout.on('data', function(data) { 
+//@   /* ... do something with data ... */ 
+//@ });
 //@ ```
 //@
 //@ Executes the given `command` _synchronously_, unless otherwise specified. 
 //@ When in synchronous mode returns the object `{ code:..., output:... }`, containing the program's 
-//@ `output` (stdout + stderr)  and its exit `code`. Otherwise the `callback` gets the 
-//@ arguments `(code, output)`.
+//@ `output` (stdout + stderr)  and its exit `code`. Otherwise returns the child process object, and
+//@ the `callback` gets the arguments `(code, output)`.
 //@
 //@ **Note:** For long-lived processes, it's best to run `exec()` asynchronously as
 //@ the current synchronous implementation uses a lot of CPU. This should be getting
@@ -837,7 +842,7 @@ function _exec(command, options, callback) {
   }, options);
 
   if (options.async)
-    execAsync(command, options, callback);
+    return execAsync(command, options, callback);
   else
     return execSync(command, options);
 };
@@ -1279,6 +1284,8 @@ function execAsync(cmd, opts, callback) {
     if (!options.silent)
       process.stdout.write(data);
   });
+
+  return c;
 }
 
 // Hack to run child_process.exec() synchronously (sync avoids callback hell)

test/exec.js

@@ -66,8 +66,9 @@ shell.cd('../..');
 //
 
 // no callback (no need for asyncFlags)
-shell.exec('node -e \"console.log(1234)\"', {async:true});
+var c = shell.exec('node -e \"console.log(1234)\"', {async:true});
 assert.equal(shell.error(), null);
+assert.ok('stdout' in c, 'async exec returns child process object');
 
 var asyncFlags = [];