The current run functions has many shortcomings and there are several issues and PRs that deal with them. This issue tries to aggregate them to get a better overview of what needs to be done:

1. globbing of $output into $lines (see run function is susceptible to globbing #281, Fix the implementation of the run helper function to properly parse lines of output #289)
   1. $lines picks up filenames from PWD when output contains * (see weird ${lines} behavior #151, Fix globbing issue in run command #152, Command output gets globbed #156, and Don't glob output #158)
   2. this also skips empty lines (see $lines keep blank empty lines in $output  #224), which might be a feature
   3. line endings are not sanitized Line endings in ${lines[@]} not sanitized #249
2. bad background task lifetime through FD3 handling within run bats waits for disowned processes even when FD3 is closed #205
3. explicitly select (only) stdout/stderr for output (see Separate stdout and stderr from the run output #2, Check stderr output #47)
4. checking the exit code on the run command itself gives better error messages (see run: add optional exit-status test #367)

• write up new documentation/tutorial section for changed run behavior -> the different use cases (check exit code, check output, ...) look very different (see README.md: more examples of (mis)using run #366) and should be achievable with the same command

My favorite solution would be to have an interface like this:

run command # works as before for backwards compatibility
# exit code checking
run ! <command> # check that command failed
run =3 <command> # check that command exited with 3
# output handling
--preserve-empty-lines # default in new mode
--skip-empty-lines # default in old mode
--separate-std-out-and-err # output contains only stdout and there is $stderr
-- # mark the end of options for commands that start with -

This should achieve all of the above goals. If possible I'd like to reuse the existing name run, but we need to evaluate if that would break existing users.