Document pipe, redirection, and semicolon properly.

[crocket]

• fish documentation doesn't say that redirection has higher precedence over pipe.
  • cmd1 ^&1 | cmd2 is not the same as cmd1 | cmd2 ^&1
  • What bash does // https://stackoverflow.com/questions/12942042/pipe-redirection-precedence
• It also doesn't say what happens if I chain redirections as in
  • cmd1 >/dev/null ^&1 or cmd1 ^&1 >/dev/null
  • What bash does // https://unix.stackexchange.com/a/176214/143227
• From the documentation, it's hard to know how to mix and match |, >, and ;.

POSIX shell specification describes syntax in nauseating details, but those details are very disorienting. Bash documentation describes syntax well.

[faho]

It also doesn't say what happens if I chain redirections as in

cmd1 >/dev/null ^&1 or cmd1 ^&1 >/dev/null

It's done left-to-right.

Fish checks the first, sees ">/dev/null", sets stdout to go to /dev/null. It sees ^&1 and sends stderr to where stdout is going, so both go to /dev/null.

Fish checks the second, sees "^&1" and sends stderr to where stdout is at that moment going, which is the terminal (unless it's already redirected from the outside). It goes on, sees ">/dev/null" and sends stdout to /dev/null, keeping stderr pointing to the terminal.

Imagine "&1" expanding to where stdout is going at that moment.

cmd1 ^&1 | cmd2 is not the same as cmd1 | cmd2 ^&1

The redirection is done after the pipe, so stdout is redirected to the pipe, and stderr is then redirected to where stdout is going, which is the pipe. So the first pipes both. The latter applies ^&1 to cmd2. To redirect both, you need begin and end, like begin; cmd1 | cmd2; end ^&1.

Also note that 3.0 deprecates the "^" redirection in favor of the standard "2>", so that last example should be cmd1 | cmd2 2>&1.

---

As far as I know, this is the same as POSIX shells (e.g. bash). In general I agree that our documentation too often assumes knowledge of that.

[crocket]

What about cmd1 | 2>&1 cmd2?

[faho]

cmd1 | 2>&1 cmd2

That's a syntax error, because the 2>&1 is in command position:

$ cmd | 2>&1 cmd2
fish: Expected a command, but instead found a redirection
cmd1 | 2>&1 cmd2
       ^

If we did allow redirections to appear before the command (POSIX does, it's not used much), it would apply to the stderr of "cmd2", which would send it to its stdout, which by default would be the terminal anyway.