This is something I intentionally left out of #394, but is something we've discussed doing. Since this would be a breaking change, I thought I'd leave it here as an open issue to see if anyone has any input.

The current behavior of shell.error() is to return the stderr output of the last command (only if it failed) or null if the command succeeded.

shell.echo('hello world');
shell.echo(shell.error()); // this is null
shell.cd('noexist');
shell.echo(shell.error()); // outputs: cd: no such file or directory: noexist

exec('git status');
if (shell.error()) {
  // git status failed
} else {
  // git status succeeded
}

If we change it to output the code returned instead, it will have the same truthiness (commands that succeed have code 0 and commands that fail have code > 0), so the last example with the if() expression still works.

Because nearly all commands return shell strings, the workaround for people relying on the error message of the commands would be to use the .stderr attribute of the return value:

var result = cp('somefile.txt', 'other.txt');
echo(result.stderr); // this will work now